diff options
| author | Nik Clayton <nik@FreeBSD.org> | 1999-08-21 18:13:33 +0000 |
|---|---|---|
| committer | Nik Clayton <nik@FreeBSD.org> | 1999-08-21 18:13:33 +0000 |
| commit | dddae37958305f8b703647900ab9944732a8ac25 (patch) | |
| tree | 1aef4e17907096b9a6779de25b4240853116f1c8 /en/handbook | |
| parent | c49d00f6013ff123e1a0039c301be00b31edeec2 (diff) | |
Notes
Diffstat (limited to 'en/handbook')
36 files changed, 0 insertions, 46478 deletions
diff --git a/en/handbook/Makefile b/en/handbook/Makefile deleted file mode 100644 index 03599ce2b8..0000000000 --- a/en/handbook/Makefile +++ /dev/null @@ -1,58 +0,0 @@ -# -# $Id: Makefile,v 1.21 1999-05-05 20:31:23 nik Exp $ -# -# Build the FreeBSD Handbook. -# - -MAINTAINER=nik@FreeBSD.ORG - -DOC?= handbook - -FORMATS?= html-split - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= handbook.sgml -SRCS+= advanced-networking/chapter.sgml -SRCS+= backups/chapter.sgml -SRCS+= basics/chapter.sgml -SRCS+= bibliography/chapter.sgml -SRCS+= contrib/chapter.sgml -SRCS+= cutting-edge/chapter.sgml -SRCS+= disks/chapter.sgml -SRCS+= eresources/chapter.sgml -SRCS+= hw/chapter.sgml -SRCS+= install/chapter.sgml -SRCS+= internals/chapter.sgml -SRCS+= introduction/chapter.sgml -SRCS+= kernelconfig/chapter.sgml -SRCS+= kerneldebug/chapter.sgml -SRCS+= kernelopts/chapter.sgml -SRCS+= l10n/chapter.sgml -SRCS+= linuxemu/chapter.sgml -SRCS+= mail/chapter.sgml -SRCS+= mirrors/chapter.sgml -SRCS+= pgpkeys/chapter.sgml -SRCS+= policies/chapter.sgml -SRCS+= ppp-and-slip/chapter.sgml -SRCS+= printing/chapter.sgml -SRCS+= quotas/chapter.sgml -SRCS+= security/chapter.sgml -SRCS+= serialcomms/chapter.sgml -SRCS+= staff/chapter.sgml -SRCS+= x11/chapter.sgml -SRCS+= ports/chapter.sgml - -# Entities -SRCS+= authors.ent -SRCS+= chapters.ent -SRCS+= mailing-lists.ent - -.include "../../share/mk/docproj.docbook.mk" diff --git a/en/handbook/advanced-networking/chapter.sgml b/en/handbook/advanced-networking/chapter.sgml deleted file mode 100644 index 8f3ecfdc06..0000000000 --- a/en/handbook/advanced-networking/chapter.sgml +++ /dev/null @@ -1,934 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.12 1999-07-28 20:23:15 nik Exp $ ---> - -<chapter id="advanced-networking"> - <title>Advanced Networking</title> - - <sect1 id="routing"> - <title>Gateways and Routes</title> - - <para><emphasis>Contributed by &a.gryphon;. 6 October - 1995.</emphasis></para> - - <para>For one machine to be able to find another, there must be a - mechanism in place to describe how to get from one to the other. This is - called Routing. A “route” is a defined pair of addresses: a - “destination” and a “gateway”. The pair - indicates that if you are trying to get to this - <emphasis>destination</emphasis>, send along through this - <emphasis>gateway</emphasis>. There are three types of destinations: - individual hosts, subnets, and “default”. The - “default route” is used if none of the other routes apply. - We will talk a little bit more about default routes later on. There are - also three types of gateways: individual hosts, interfaces (also called - “links”), and ethernet hardware addresses.</para> - - <sect2> - <title>An example</title> - - <para>To illustrate different aspects of routing, we will use the - following example which is the output of the command <command>netstat - -r</command>:</para> - - <screen>Destination Gateway Flags Refs Use Netif Expire - -default outside-gw UGSc 37 418 ppp0 -localhost localhost UH 0 181 lo0 -test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77 -10.20.30.255 link#1 UHLW 1 2421 -foobar.com link#1 UC 0 0 -host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 -host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => -host2.foobar.com link#1 UC 0 0 -224 link#1 UC 0 0</screen> - - <para>The first two lines specify the default route (which we will cover - in the next section) and the <hostid>localhost</hostid> route.</para> - - <para>The interface (<literal>Netif</literal> column) that it specifies - to use for <literal>localhost</literal> is - <devicename>lo0</devicename>, also known as the loopback device. This - says to keep all traffic for this destination internal, rather than - sending it out over the LAN, since it will only end up back where it - started anyway.</para> - - <para>The next thing that stands out are the <hostid - role="mac">0:e0:...</hostid> addresses. These are ethernet hardware - addresses. FreeBSD will automatically identify any hosts - (<hostid>test0</hostid> in the example) on the local ethernet and add - a route for that host, directly to it over the ethernet interface, - <devicename>ed0</devicename>. There is also a timeout - (<literal>Expire</literal> column) associated with this type of route, - which is used if we fail to hear from the host in a specific amount of - time. In this case the route will be automatically deleted. These - hosts are identified using a mechanism known as RIP (Routing - Information Protocol), which figures out routes to local hosts based - upon a shortest path determination.</para> - - <para>FreeBSD will also add subnet routes for the local subnet (<hostid - role="ipaddr">10.20.30.255</hostid> is the broadcast address for the - subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid - role="domainname">foobar.com</hostid> is the domain name associated - with that subnet). The designation <literal>link#1</literal> refers - to the first ethernet card in the machine. You will notice no - additional interface is specified for those.</para> - - <para>Both of these groups (local network hosts and local subnets) have - their routes automatically configured by a daemon called - <command>routed</command>. If this is not run, then only routes which - are statically defined (ie. entered explicitly) will exist.</para> - - <para>The <literal>host1</literal> line refers to our host, which it - knows by ethernet address. Since we are the sending host, FreeBSD - knows to use the loopback interface (<devicename>lo0</devicename>) - rather than sending it out over the ethernet interface.</para> - - <para>The two <literal>host2</literal> lines are an example of what - happens when we use an ifconfig alias (see the section of ethernet for - reasons why we would do this). The <literal>=></literal> symbol - after the <devicename>lo0</devicename> interface says that not only - are we using the loopback (since this is address also refers to the - local host), but specifically it is an alias. Such routes only show - up on the host that supports the alias; all other hosts on the local - network will simply have a <literal>link#1</literal> line for - such.</para> - - <para>The final line (destination subnet <literal>224</literal>) deals - with MultiCasting, which will be covered in a another section.</para> - - <para>The other column that we should talk about are the - <literal>Flags</literal>. Each route has different attributes that - are described in the column. Below is a short table of some of these - flags and their meanings:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry>U</entry> - <entry>Up: The route is active.</entry> - </row> - - <row> - <entry>H</entry> - <entry>Host: The route destination is a single host.</entry> - </row> - - <row> - <entry>G</entry> - <entry>Gateway: Send anything for this destination on to this - remote system, which will figure out from there where to send - it.</entry> - </row> - - <row> - <entry>S</entry> - <entry>Static: This route was configured manually, not - automatically generated by the system.</entry> - </row> - - <row> - <entry>C</entry> - <entry>Clone: Generates a new route based upon this route for - machines we connect to. This type of route is normally used - for local networks.</entry> - </row> - - <row> - <entry>W</entry> - <entry>WasCloned: Indicated a route that was auto-configured - based upon a local area network (Clone) route.</entry> - </row> - - <row> - <entry>L</entry> - <entry>Link: Route involves references to ethernet - hardware.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Default routes</title> - - <para>When the local system needs to make a connection to remote host, - it checks the routing table to determine if a known path exists. If - the remote host falls into a subnet that we know how to reach (Cloned - routes), then the system checks to see if it can connect along that - interface.</para> - - <para>If all known paths fail, the system has one last option: the - “default” route. This route is a special type of gateway - route (usually the only one present in the system), and is always - marked with a <literal>c</literal> in the flags field. For hosts on a - local area network, this gateway is set to whatever machine has a - direct connection to the outside world (whether via PPP link, or your - hardware device attached to a dedicated data line).</para> - - <para>If you are configuring the default route for a machine which - itself is functioning as the gateway to the outside world, then the - default route will be the gateway machine at your Internet Service - Provider's (ISP) site.</para> - - <para>Let us look at an example of default routes. This is a common - configuration:</para> - - <literallayout> -[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW] - </literallayout> - - <para>The hosts <hostid>Local1</hostid> and <hostid>Local2</hostid> are - at your site, with the formed being your PPP connection to your ISP's - Terminal Server. Your ISP has a local network at their site, which - has, among other things, the server where you connect and a hardware - device (T1-GW) attached to the ISP's Internet feed.</para> - - <para>The default routes for each of your machines will be:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>host</entry> - <entry>default gateway</entry> - <entry>interface</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Local2</entry> - <entry>Local1</entry> - <entry>ethernet</entry> - </row> - - <row> - <entry>Local1</entry> - <entry>T1-GW</entry> - <entry>PPP</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>A common question is “Why (or how) would we set the T1-GW to - be the default gateway for Local1, rather than the ISP server it is - connected to?”.</para> - - <para>Remember, since the PPP interface is using an address on the ISP's - local network for your side of the connection, routes for any other - machines on the ISP's local network will be automatically generated. - Hence, you will already know how to reach the T1-GW machine, so there - is no need for the intermediate step of sending traffic to the ISP - server.</para> - - <para>As a final note, it is common to use the address <hostid - role="ipaddr">...1</hostid> as the gateway address for your local - network. So (using the same example), if your local class-C address - space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was - using <hostid role="ipaddr">10.9.9</hostid> then the default routes - would be:</para> - - <literallayout> -Local2 (10.20.30.2) --> Local1 (10.20.30.1) -Local1 (10.20.30.1, 10.9.9.30) --> T1-GW (10.9.9.1) - </literallayout> - </sect2> - - <sect2> - <title>Dual homed hosts</title> - - <para>There is one other type of configuration that we should cover, and - that is a host that sits on two different networks. Technically, any - machine functioning as a gateway (in the example above, using a PPP - connection) counts as a dual-homed host. But the term is really only - used to refer to a machine that sits on two local-area - networks.</para> - - <para>In one case, the machine as two ethernet cards, each having an - address on the separate subnets. Alternately, the machine may only - have one ethernet card, and be using ifconfig aliasing. The former is - used if two physically separate ethernet networks are in use, the - latter if there is one physical network segment, but two logically - separate subnets.</para> - - <para>Either way, routing tables are set up so that each subnet knows - that this machine is the defined gateway (inbound route) to the other - subnet. This configuration, with the machine acting as a Bridge - between the two subnets, is often used when we need to implement - packet filtering or firewall security in either or both - directions.</para> - </sect2> - - <sect2> - <title>Routing propagation</title> - - <para>We have already talked about how we define our routes to the - outside world, but not about how the outside world finds us.</para> - - <para>We already know that routing tables can be set up so that all - traffic for a particular address space (in our examples, a class-C - subnet) can be sent to a particular host on that network, which will - forward the packets inbound.</para> - - <para>When you get an address space assigned to your site, your service - provider will set up their routing tables so that all traffic for your - subnet will be sent down your PPP link to your site. But how do sites - across the country know to send to your ISP?</para> - - <para>There is a system (much like the distributed DNS information) that - keeps track of all assigned address-spaces, and defines their point of - connection to the Internet Backbone. The “Backbone” are - the main trunk lines that carry Internet traffic across the country, - and around the world. Each backbone machine has a copy of a master - set of tables, which direct traffic for a particular network to a - specific backbone carrier, and from there down the chain of service - providers until it reaches your network.</para> - - <para>It is the task of your service provider to advertise to the - backbone sites that they are the point of connection (and thus the - path inward) for your site. This is known as route - propagation.</para> - </sect2> - - <sect2> - <title>Troubleshooting</title> - - <para>Sometimes, there is a problem with routing propagation, and some - sites are unable to connect to you. Perhaps the most useful command - for trying to figure out where a routing is breaking down is the - &man.traceroute.8; command. It is equally useful if you cannot seem - to make a connection to a remote machine (i.e. &man.ping.8; - fails).</para> - - <para>The &man.traceroute.8; command is run with the name of the remote - host you are trying to connect to. It will show the gateway hosts - along the path of the attempt, eventually either reaching the target - host, or terminating because of a lack of connection.</para> - - <para>For more information, see the manual page for - &man.traceroute.8;.</para> - </sect2> - </sect1> - - <sect1 id="nfs"> - <title>NFS</title> - - <para><emphasis>Contributed by &a.jlind;.</emphasis></para> - - <para>Certain Ethernet adapters for ISA PC systems have limitations which - can lead to serious network problems, particularly with NFS. This - difficulty is not specific to FreeBSD, but FreeBSD systems are affected - by it.</para> - - <para>The problem nearly always occurs when (FreeBSD) PC systems are - networked with high-performance workstations, such as those made by - Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS mount will - work fine, and some operations may succeed, but suddenly the server will - seem to become unresponsive to the client, even though requests to and - from other systems continue to be processed. This happens to the client - system, whether the client is the FreeBSD system or the workstation. On - many systems, there is no way to shut down the client gracefully once - this problem has manifested itself. The only solution is often to reset - the client, because the NFS situation cannot be resolved.</para> - - <para>Though the “correct” solution is to get a higher - performance and capacity Ethernet adapter for the FreeBSD system, there - is a simple workaround that will allow satisfactory operation. If the - FreeBSD system is the <emphasis>server</emphasis>, include the option - <option>-w=1024</option> on the mount from the client. If the FreeBSD - system is the <emphasis>client</emphasis>, then mount the NFS file - system with the option <option>-r=1024</option>. These options may be - specified using the fourth field of the <filename>fstab</filename> entry - on the client for automatic mounts, or by using the <option>-o</option> - parameter of the mount command for manual mounts.</para> - - <para>It should be noted that there is a different problem, sometimes - mistaken for this one, when the NFS servers and clients are on different - networks. If that is the case, make <emphasis>certain</emphasis> that - your routers are routing the necessary UDP information, or you will not - get anywhere, no matter what else you are doing.</para> - - <para>In the following examples, <hostid>fastws</hostid> is the host - (interface) name of a high-performance workstation, and - <hostid>freebox</hostid> is the host (interface) name of a FreeBSD - system with a lower-performance Ethernet adapter. Also, - <filename>/sharedfs</filename> will be the exported NFS filesystem (see - <command>man exports</command>), and <filename>/project</filename> will - be the mount point on the client for the exported file system. In all - cases, note that additional options, such as <option>hard</option> or - <option>soft</option> and <option>bg</option> may be desirable in your - application.</para> - - <para>Examples for the FreeBSD system (<hostid>freebox</hostid>) as the - client: in <filename>/etc/fstab</filename> on freebox:</para> - - <programlisting> -fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting> - - <para>As a manual mount command on <hostid>freebox</hostid>:</para> - - <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen> - - <para>Examples for the FreeBSD system as the server: in - <filename>/etc/fstab</filename> on <hostid>fastws</hostid>:</para> - - <programlisting> -freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting> - - <para>As a manual mount command on <hostid>fastws</hostid>:</para> - - <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen> - - <para>Nearly any 16-bit Ethernet adapter will allow operation without the - above restrictions on the read or write size.</para> - - <para>For anyone who cares, here is what happens when the failure occurs, - which also explains why it is unrecoverable. NFS typically works with a - “block” size of 8k (though it may do fragments of smaller - sizes). Since the maximum Ethernet packet is around 1500 bytes, the NFS - “block” gets split into multiple Ethernet packets, even - though it is still a single unit to the upper-level code, and must be - received, assembled, and <emphasis>acknowledged</emphasis> as a unit. - The high-performance workstations can pump out the packets which - comprise the NFS unit one right after the other, just as close together - as the standard allows. On the smaller, lower capacity cards, the later - packets overrun the earlier packets of the same unit before they can be - transferred to the host and the unit as a whole cannot be reconstructed - or acknowledged. As a result, the workstation will time out and try - again, but it will try again with the entire 8K unit, and the process - will be repeated, ad infinitum.</para> - - <para>By keeping the unit size below the Ethernet packet size limitation, - we ensure that any complete Ethernet packet received can be acknowledged - individually, avoiding the deadlock situation.</para> - - <para>Overruns may still occur when a high-performance workstations is - slamming data out to a PC system, but with the better cards, such - overruns are not guaranteed on NFS “units”. When an overrun - occurs, the units affected will be retransmitted, and there will be a - fair chance that they will be received, assembled, and - acknowledged.</para> - </sect1> - - <sect1 id="diskless"> - <title>Diskless Operation</title> - - <para><emphasis>Contributed by &a.martin;.</emphasis></para> - - <para><filename>netboot.com</filename>/<filename>netboot.rom</filename> - allow you to boot your FreeBSD machine over the network and run FreeBSD - without having a disk on your client. Under 2.0 it is now possible to - have local swap. Swapping over NFS is also still supported.</para> - - <para>Supported Ethernet cards include: Western Digital/SMC 8003, 8013, - 8216 and compatibles; NE1000/NE2000 and compatibles (requires - recompile)</para> - - <sect2> - <title>Setup Instructions</title> - - <procedure> - <step> - <para>Find a machine that will be your server. This machine will - require enough disk space to hold the FreeBSD 2.0 binaries and - have bootp, tftp and NFS services available. Tested - machines:</para> - - <itemizedlist> - <listitem> - <para>HP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't - work)</para> - </listitem> - - <listitem> - <para>Sun/Solaris 2.3. (you may need to get bootp)</para> - </listitem> - </itemizedlist> - </step> - - <step> - <para>Set up a bootp server to provide the client with IP, gateway, - netmask.</para> - - <programlisting> -diskless:\ - :ht=ether:\ - :ha=0000c01f848a:\ - :sm=255.255.255.0:\ - :hn:\ - :ds=192.1.2.3:\ - :ip=192.1.2.4:\ - :gw=192.1.2.5:\ - :vm=rfc1048:</programlisting> - </step> - - <step> - <para>Set up a TFTP server (on same machine as bootp server) to - provide booting information to client. The name of this file is - <filename>cfg.<replaceable>X.X.X.X</replaceable></filename> (or - <filename>/tftpboot/cfg.<replaceable>X.X.X.X</replaceable></filename>, - it will try both) where <replaceable>X.X.X.X</replaceable> is the - IP address of the client. The contents of this file can be any - valid netboot commands. Under 2.0, netboot has the following - commands:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry>help</entry> - <entry>print help list</entry> - </row> - - <row> - <entry>ip - <option><replaceable>X.X.X.X</replaceable></option></entry> - <entry>print/set client's IP address</entry> - </row> - - <row> - <entry>server - <option><replaceable>X.X.X.X</replaceable></option></entry> - <entry>print/set bootp/tftp server address</entry> - </row> - - <row> - <entry>netmask - <option><replaceable>X.X.X.X</replaceable></option></entry> - <entry>print/set netmask</entry> - </row> - - <row> - <entry>hostname <replaceable>name</replaceable></entry> - <entry>print/set hostname</entry> - </row> - - <row> - <entry>kernel - <option><replaceable>name</replaceable></option></entry> - <entry>print/set kernel name</entry> - </row> - - <row> - <entry>rootfs - <option><replaceable>ip:/fs</replaceable></option></entry> - <entry>print/set root filesystem</entry> - </row> - - <row> - <entry>swapfs - <option><replaceable>ip:/fs</replaceable></option></entry> - <entry>print/set swap filesystem</entry> - </row> - - <row> - <entry>swapsize - <option><replaceable>size</replaceable></option></entry> - <entry>set diskless swapsize in Kbytes</entry> - </row> - - <row> - <entry>diskboot</entry> - <entry>boot from disk</entry> - </row> - - <row> - <entry>autoboot</entry> - <entry>continue boot process</entry> - </row> - - <row> - <entry>trans - <option>on</option>|<option>off</option></entry> - <entry>turn transceiver on|off</entry> - </row> - - <row> - <entry>flags - <option>b</option><option>c</option><option>d</option><option>h</option><option>s</option><option>v</option></entry> - <entry>set boot flags</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>A typical completely diskless cfg file might contain:</para> - - <programlisting> -rootfs 192.1.2.3:/rootfs/myclient -swapfs 192.1.2.3:/swapfs -swapsize 20000 -hostname myclient.mydomain</programlisting> - - <para>A cfg file for a machine with local swap might contain:</para> - - <programlisting> -rootfs 192.1.2.3:/rootfs/myclient -hostname myclient.mydomain</programlisting> - </step> - - <step> - <para>Ensure that your NFS server has exported the root (and swap if - applicable) filesystems to your client, and that the client has - root access to these filesystems A typical - <filename>/etc/exports</filename> file on FreeBSD might look - like:</para> - - <programlisting> -/rootfs/myclient -maproot=0:0 myclient.mydomain -/swapfs -maproot=0:0 myclient.mydomain</programlisting> - - <para>And on HP-UX:</para> - - <programlisting> -/rootfs/myclient -root=myclient.mydomain -/swapfs -root=myclient.mydomain</programlisting> - </step> - - <step> - <para>If you are swapping over NFS (completely diskless - configuration) create a swap file for your client using - <command>dd</command>. If your <command>swapfs</command> command - has the arguments <filename>/swapfs</filename> and the size 20000 - as in the example above, the swapfile for myclient will be called - <filename>/swapfs/swap.<replaceable>X.X.X.X</replaceable></filename> - where <replaceable>X.X.X.X</replaceable> is the client's IP addr, - eg:</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000</userinput></screen> - - <para>Also, the client's swap space might contain sensitive - information once swapping starts, so make sure to restrict read - and write access to this file to prevent unauthorized - access:</para> - - <screen>&prompt.root; <userinput>chmod 0600 /swapfs/swap.192.1.2.4</userinput></screen> - </step> - - <step> - <para>Unpack the root filesystem in the directory the client will - use for its root filesystem (<filename>/rootfs/myclient</filename> - in the example above).</para> - - <itemizedlist> - <listitem> - <para>On HP-UX systems: The server should be running HP-UX 9.04 - or later for HP9000/800 series machines. Prior versions do not - allow the creation of device files over NFS.</para> - </listitem> - - <listitem> - <para>When extracting <filename>/dev</filename> in - <filename>/rootfs/myclient</filename>, beware that some - systems (HPUX) will not create device files that FreeBSD is - happy with. You may have to go to single user mode on the - first bootup (press control-c during the bootup phase), cd - <filename>/dev</filename> and do a <command>sh ./MAKEDEV - all</command> from the client to fix this.</para> - </listitem> - </itemizedlist> - </step> - - <step> - <para>Run <command>netboot.com</command> on the client or make an - EPROM from the <filename>netboot.rom</filename> file</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Using Shared <filename>/</filename> and <filename>/usr</filename> - filesystems</title> - - <para>At present there isn't an officially sanctioned way of doing this, - although I have been using a shared <filename>/usr</filename> - filesystem and individual <filename>/</filename> filesystems for each - client. If anyone has any suggestions on how to do this cleanly, - please let me and/or the &a.core; know.</para> - </sect2> - - <sect2> - <title>Compiling netboot for specific setups</title> - - <para>Netboot can be compiled to support NE1000/2000 cards by changing - the configuration in - <filename>/sys/i386/boot/netboot/Makefile</filename>. See the - comments at the top of this file.</para> - </sect2> - </sect1> - - <sect1 id="isdn"> - <title>ISDN</title> - - <para><emphasis>Last modified by &a.wlloyd;</emphasis>.</para> - - <para>A good resource for information on ISDN technology and hardware is - <ulink URL="http://alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN - Page</ulink>.</para> - - <para>A quick simple roadmap to ISDN follows:</para> - - <itemizedlist> - <listitem> - <para>If you live in Europe I suggest you investigate the ISDN card - section.</para> - </listitem> - - <listitem> - <para>If you are planning to use ISDN primarily to connect to the - Internet with an Internet Provider on a dialup non-dedicated basis, - I suggest you look into Terminal Adapters. This will give you the - most flexibility, with the fewest problems, if you change - providers.</para> - </listitem> - - <listitem> - <para>If you are connecting two lans together, or connecting to the - Internet with a dedicated ISDN connection, I suggest you consider - the stand alone router/bridge option.</para> - </listitem> - </itemizedlist> - - <para>Cost is a significant factor in determining what solution you will - choose. The following options are listed from least expensive to most - expensive.</para> - - <sect2> - <title>ISDN Cards</title> - - <para><emphasis>Contributed by &a.hm;.</emphasis></para> - - <para>This section is really only relevant to ISDN users in countries - where the DSS1/Q.931 ISDN standard is supported.</para> - - <para>Some growing number of PC ISDN cards are supported under FreeBSD - 2.2.x and up by the isdn4bsd driver package. It is still under - development but the reports show that it is successfully used all over - Europe.</para> - - <para>The latest isdn4bsd version is available from <ulink - url="ftp://isdn4bsd@ftp.consol.de/pub/">ftp://isdn4bsd@ftp.consol.de/pub/</ulink>, - the main isdn4bsd ftp site (you have to log in as user - <username>isdn4bsd</username> , give your mail address as the password - and change to the <filename>pub</filename> directory. Anonymous ftp - as user <username>ftp</username> or <username>anonymous</username> - will <emphasis>not</emphasis> give the desired result).</para> - - <para>Isdn4bsd allows you to connect to other ISDN routers using either - IP over raw HDLC or by using synchronous PPP. A telephone answering - machine application is also available.</para> - - <para>Many ISDN PC cards are supported, mostly the ones with a Siemens - ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola, - Cologne Chip Designs) is currently under development. For an - up-to-date list of supported cards, please have a look at the <ulink - url="ftp://isdn4bsd@ftp.consol.de/pub/README">README</ulink> - file.</para> - - <para>In case you are interested in adding support for a different ISDN - protocol, a currently unsupported ISDN PC card or otherwise enhancing - isdn4bsd, please get in touch with <email>hm@kts.org</email>.</para> - - <para>A majordomo maintained mailing list is available. To join the - list, send mail to <email>majordomo@FreeBSD.org</email> and - specify:</para> - - <programlisting> -subscribe freebsd-isdn</programlisting> - - <para>in the body of your message.</para> - </sect2> - - <sect2> - <title>ISDN Terminal Adapters</title> - - <para>Terminal adapters(TA), are to ISDN what modems are to regular - phone lines.</para> - - <para>Most TA's use the standard hayes modem AT command set, and can be - used as a drop in replacement for a modem.</para> - - <para>A TA will operate basically the same as a modem except connection - and throughput speeds will be much faster than your old modem. You - will need to configure <link linkend="ppp">PPP</link> exactly the same - as for a modem setup. Make sure you set your serial speed as high as - possible.</para> - - <para>The main advantage of using a TA to connect to an Internet - Provider is that you can do Dynamic PPP. As IP address space becomes - more and more scarce, most providers are not willing to provide you - with a static IP anymore. Most standalone routers are not able to - accommodate dynamic IP allocation.</para> - - <para>TA's completely rely on the PPP daemon that you are running for - their features and stability of connection. This allows you to - upgrade easily from using a modem to ISDN on a FreeBSD machine, if you - already have PPP setup. However, at the same time any problems you - experienced with the PPP program and are going to persist.</para> - - <para>If you want maximum stability, use the kernel <link - linkend="ppp">PPP</link> option, not the user-land <link - linkend="userppp">iijPPP</link>.</para> - - <para>The following TA's are know to work with FreeBSD.</para> - - <itemizedlist> - <listitem> - <para>Motorola BitSurfer and Bitsurfer Pro</para> - </listitem> - - <listitem> - <para>Adtran</para> - </listitem> - </itemizedlist> - - <para>Most other TA's will probably work as well, TA vendors try to make - sure their product can accept most of the standard modem AT command - set.</para> - - <para>The real problem with external TA's is like modems you need a good - serial card in your computer.</para> - - <para>You should read the <link linkend="uart">serial ports</link> - section in the handbook for a detailed understanding of serial - devices, and the differences between asynchronous and synchronous - serial ports.</para> - - <para>A TA running off a standard PC serial port (asynchronous) limits - you to 115.2Kbs, even though you have a 128Kbs connection. To fully - utilize the 128Kbs that ISDN is capable of, you must move the TA to a - synchronous serial card.</para> - - <para>Do not be fooled into buying an internal TA and thinking you have - avoided the synchronous/asynchronous issue. Internal TA's simply have - a standard PC serial port chip built into them. All this will do, is - save you having to buy another serial cable, and find another empty - electrical socket.</para> - - <para>A synchronous card with a TA is at least as fast as a standalone - router, and with a simple 386 FreeBSD box driving it, probably more - flexible.</para> - - <para>The choice of sync/TA vs standalone router is largely a religious - issue. There has been some discussion of this in the mailing lists. - I suggest you search the <ulink - URL="http://www.FreeBSD.org/search.html">archives</ulink> for the - complete discussion.</para> - </sect2> - - <sect2> - <title>Standalone ISDN Bridges/Routers</title> - - <para>ISDN bridges or routers are not at all specific to FreeBSD or any - other operating system. For a more complete description of routing - and bridging technology, please refer to a Networking reference - book.</para> - - <para>In the context of this page, I will use router and bridge - interchangeably.</para> - - <para>As the cost of low end ISDN routers/bridges comes down, it will - likely become a more and more popular choice. An ISDN router is a - small box that plugs directly into your local Ethernet network(or - card), and manages its own connection to the other bridge/router. It - has all the software to do PPP and other protocols built in.</para> - - <para>A router will allow you much faster throughput that a standard TA, - since it will be using a full synchronous ISDN connection.</para> - - <para>The main problem with ISDN routers and bridges is that - interoperability between manufacturers can still be a problem. If you - are planning to connect to an Internet provider, I recommend that you - discuss your needs with them.</para> - - <para>If you are planning to connect two lan segments together, ie: home - lan to the office lan, this is the simplest lowest maintenance - solution. Since you are buying the equipment for both sides of the - connection you can be assured that the link will work.</para> - - <para>For example to connect a home computer or branch office network to - a head office network the following setup could be used.</para> - - <example> - <title>Branch office or Home network</title> - - <para>Network is 10 Base T Ethernet. Connect router to network cable - with AUI/10BT transceiver, if necessary.</para> - - <!-- This should be a graphic --> - <programlisting> ----Sun workstation -| ----FreeBSD box -| ----Windows 95 (Do not admit to owning it) -| -Standalone router - | -ISDN BRI line</programlisting> - - <para>If your home/branch office is only one computer you can use a - twisted pair crossover cable to connect to the standalone router - directly.</para> - </example> - - <example> - <title>Head office or other lan</title> - - <para>Network is Twisted Pair Ethernet.</para> - - <!-- This should be a graphic --> - <programlisting> - -------Novell Server - | H | - | ---Sun - | | - | U ---FreeBSD - | | - | ---Windows 95 - | B | - |___---Standalone router - | - ISDN BRI line</programlisting> - </example> - - <para>One large advantage of most routers/bridges is that they allow you - to have 2 <emphasis>separate independent</emphasis> PPP connections to - 2 separate sites at the <emphasis>same</emphasis> time. This is not - supported on most TA's, except for specific(expensive) models that - have two serial ports. Do not confuse this with channel bonding, MPP - etc.</para> - - <para>This can be very useful feature, for example if you have an - dedicated internet ISDN connection at your office and would like to - tap into it, but don't want to get another ISDN line at work. A router - at the office location can manage a dedicated B channel connection - (64Kbs) to the internet, as well as a use the other B channel for a - separate data connection. The second B channel can be used for - dialin, dialout or dynamically bond(MPP etc.) with the first B channel - for more bandwidth.</para> - - <para>An Ethernet bridge will also allow you to transmit more than just - IP traffic, you can also send IPX/SPX or whatever other protocols you - use.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/authors.ent b/en/handbook/authors.ent deleted file mode 100644 index 2410a05075..0000000000 --- a/en/handbook/authors.ent +++ /dev/null @@ -1,399 +0,0 @@ -<!-- - Names and email address of contributing authors and CVS committers. - Entity names for committers should be the same as their login names on - freefall.FreeBSD.org. - - Use these entities when referencing people. - - Please keep this list in alphabetical order by entity names. - - $Id: authors.ent,v 1.43 1999-08-11 13:53:12 alfred Exp $ ---> - -<!ENTITY a.abial "Andrzej Bialecki <email>abial@FreeBSD.org</email>"> - -<!ENTITY a.ache "Andrey A. Chernov <email>ache@FreeBSD.org</email>"> - -<!ENTITY a.adam "Adam David <email>adam@FreeBSD.org</email>"> - -<!ENTITY a.alc "Alan L. Cox <email>alc@FreeBSD.org</email>"> - -<!ENTITY a.alex "Alex Nash <email>alex@FreeBSD.org</email>"> - -<!ENTITY a.alfred "Alfred Perlstein <email>alfred@FreeBSD.org</email>"> - -<!ENTITY a.amurai "Atsushi Murai <email>amurai@FreeBSD.org</email>"> - -<!ENTITY a.andreas "Andreas Klemm <email>andreas@FreeBSD.org</email>"> - -<!ENTITY a.archie "Archie Cobbs <email>archie@FreeBSD.org</email>"> - -<!ENTITY a.asami "Satoshi Asami <email>asami@FreeBSD.org</email>"> - -<!ENTITY a.ats "Andreas Schulz <email>ats@FreeBSD.org</email>"> - -<!ENTITY a.awebster "Andrew Webster <email>awebster@pubnix.net</email>"> - -<!ENTITY a.bde "Bruce Evans <email>bde@FreeBSD.org</email>"> - -<!ENTITY a.billf "Bill Fumerola <email>billf@FreeBSD.org</email>"> - -<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.org</email>"> - -<!ENTITY a.brian "Brian Somers <email>brian@FreeBSD.org</email>"> - -<!ENTITY a.cawimm "Charles A. Wimmer <email>cawimm@FreeBSD.org</email>"> - -<!ENTITY a.cg "Cameron Grant <email>cg@FreeBSD.org</email>"> - -<!ENTITY a.charnier "Philippe Charnier <email>charnier@FreeBSD.org</email>"> - -<!ENTITY a.chris "Chris Costello <email>chris@FreeBSD.org</email>"> - -<!ENTITY a.chuck "Chuck Robey <email>chuckr@glue.umd.edu</email>"> - -<!ENTITY a.chuckr "Chuck Robey <email>chuckr@FreeBSD.org</email>"> - -<!ENTITY a.cpiazza "Chris Piazza <email>cpiazza@FreeBSD.org</email>"> - -<!ENTITY a.cracauer "Martin Cracauer <email>cracauer@FreeBSD.org</email>"> - -<!ENTITY a.csgr "Geoff Rehmet <email>csgr@FreeBSD.org</email>"> - -<!ENTITY a.cwt "Chris Timmons <email>cwt@FreeBSD.org</email>"> - -<!ENTITY a.danny "Daniel O'Callaghan <email>danny@FreeBSD.org</email>"> - -<!ENTITY a.darrenr "Darren Reed <email>darrenr@FreeBSD.org</email>"> - -<!ENTITY a.davidn "David Nugent <email>davidn@blaze.net.au</email>"> - -<!ENTITY a.dbaker "Daniel Baker <email>dbaker@FreeBSD.org</email>"> - -<!ENTITY a.dburr "Donald Burr <email>dburr@FreeBSD.org</email>"> - -<!ENTITY a.dcs "Daniel C. Sobral <email>dcs@FreeBSD.org</email>"> - -<!ENTITY a.deischen "Daniel Eischen <email>deischen@FreeBSD.org</email>"> - -<!ENTITY a.des "Dag-Erling C. Smørgrav <email>des@FreeBSD.org</email>"> - -<!ENTITY a.dfr "Doug Rabson <email>dfr@FreeBSD.org</email>"> - -<!ENTITY a.dg "David Greenman <email>dg@FreeBSD.org</email>"> - -<!ENTITY a.dick "Richard Seaman Jr. <email>dick@FreeBSD.org</email>"> - -<!ENTITY a.dillon "Matthew Dillon <email>dillon@FreeBSD.org</email>"> - -<!ENTITY a.dima "Dima Ruban <email>dima@FreeBSD.org</email>"> - -<!ENTITY a.dirk "Dirk Frömberg <email>dirk@FreeBSD.org</email>"> - -<!ENTITY a.dirkvangulik "Dirk-Willem van Gulik <email>Dirk.vanGulik@jrc.it</email>"> - -<!ENTITY a.dt "Dmitrij Tejblum <email>dt@FreeBSD.org</email>"> - -<!ENTITY a.dufault "Peter Dufault <email>dufault@FreeBSD.org</email>"> - -<!ENTITY a.dwhite "Doug White <email>dwhite@FreeBSD.org</email>"> - -<!ENTITY a.dyson "John Dyson <email>dyson@FreeBSD.org</email>"> - -<!ENTITY a.eivind "Eivind Eklund <email>eivind@FreeBSD.org</email>"> - -<!ENTITY a.ejc "Eric J. Chet <email>ejc@FreeBSD.org</email>"> - -<!ENTITY a.erich "Eric L. Hernes <email>erich@FreeBSD.org</email>"> - -<!ENTITY a.faq "FAQ Maintainer <email>faq@FreeBSD.org</email>"> - -<!ENTITY a.fenner "Bill Fenner <email>fenner@FreeBSD.org</email>"> - -<!ENTITY a.flathill "Seiichirou Hiraoka <email>flathill@FreeBSD.org</email>"> - -<!ENTITY a.foxfair "Howard F. Hu <email>foxfair@FreeBSD.org</email>"> - -<!ENTITY a.fsmp "Steve Passe <email>fsmp@FreeBSD.org</email>"> - -<!ENTITY a.gallatin "Andrew Gallatin <email>gallatin@FreeBSD.org</email>"> - -<!ENTITY a.gclarkii "Gary Clark II <email>gclarkii@FreeBSD.org</email>"> - -<!ENTITY a.gehenna "Masahide MAEKAWA <email>gehenna@FreeBSD.org</email>"> - -<!ENTITY a.gena "Gennady B. Sorokopud <email>gena@NetVision.net.il</email>"> - -<!ENTITY a.ghelmer "Guy Helmer <email>ghelmer@cs.iastate.edu</email>"> - -<!ENTITY a.gibbs "Justin T. Gibbs <email>gibbs@FreeBSD.org</email>"> - -<!ENTITY a.gj "Gary Jennejohn <email>gj@FreeBSD.org</email>"> - -<!ENTITY a.gpalmer "Gary Palmer <email>gpalmer@FreeBSD.org</email>"> - -<!ENTITY a.graichen "Thomas Graichen <email>graichen@FreeBSD.org</email>"> - -<!ENTITY a.green "Brian F. Feldman <email>green@FreeBSD.org</email>"> - -<!ENTITY a.grog "Greg Lehey <email>grog@FreeBSD.org</email>"> - -<!ENTITY a.gryphon "Coranth Gryphon <email>gryphon@healer.com</email>"> - -<!ENTITY a.guido "Guido van Rooij <email>guido@FreeBSD.org</email>"> - -<!ENTITY a.hanai "Hiroyuki HANAI <email>hanai@FreeBSD.org</email>"> - -<!ENTITY a.handy "Brian N. Handy <email>handy@sxt4.physics.montana.edu</email>"> - -<!ENTITY a.helbig "Wolfgang Helbig <email>helbig@FreeBSD.org</email>"> - -<!ENTITY a.hm "Hellmuth Michaelis <email>hm@FreeBSD.org</email>"> - -<!ENTITY a.hoek "Tim Vanderhoek <email>hoek@FreeBSD.org</email>"> - -<!ENTITY a.hosokawa "Tatsumi Hosokawa <email>hosokawa@FreeBSD.org</email>"> - -<!ENTITY a.hsu "Jeffrey Hsu <email>hsu@FreeBSD.org</email>"> - -<!ENTITY a.imp "Warner Losh <email>imp@FreeBSD.org</email>"> - -<!ENTITY a.itojun "Jun-ichiro Itoh <email>itojun@itojun.org</email>"> - -<!ENTITY a.iwasaki "Mitsuru IWASAKI <email>iwasaki@FreeBSD.org</email>"> - -<!ENTITY a.jasone "Jason Evans <email>jasone@FreeBSD.org</email>"> - -<!ENTITY a.jb "John Birrell <email>jb@cimlogic.com.au</email>"> - -<!ENTITY a.jdp "John Polstra <email>jdp@FreeBSD.org</email>"> - -<!ENTITY a.jehamby "Jake Hamby <email>jehamby@lightside.com</email>"> - -<!ENTITY a.jfieber "John Fieber <email>jfieber@FreeBSD.org</email>"> - -<!ENTITY a.jfitz "James FitzGibbon <email>jfitz@FreeBSD.org</email>"> - -<!ENTITY a.jgreco "Joe Greco <email>jgreco@FreeBSD.org</email>"> - -<!ENTITY a.jhay "John Hay <email>jhay@FreeBSD.org</email>"> - -<!ENTITY a.jhs "Julian Stacey <email>jhs@FreeBSD.org</email>"> - -<!ENTITY a.jim "Jim Mock <email>jim@FreeBSD.org</email>"> - -<!ENTITY a.jkh "Jordan K. Hubbard <email>jkh@FreeBSD.org</email>"> - -<!ENTITY a.jkoshy "Joseph Koshy <email>jkoshy@FreeBSD.org</email>"> - -<!ENTITY a.jlemon "Jonathan Lemon <email>jlemon@FreeBSD.org</email>"> - -<!ENTITY a.jlind "John Lind <email>john@starfire.MN.ORG</email>"> - -<!ENTITY a.jlrobin "James L. Robinson <email>jlrobin@FreeBSD.org</email>"> - -<!ENTITY a.jmacd "Joshua Peck Macdonald <email>jmacd@FreeBSD.org</email>"> - -<!ENTITY a.jmb "Jonathan M. Bresler <email>jmb@FreeBSD.org</email>"> - -<!ENTITY a.jmg "John-Mark Gurney <email>jmg@FreeBSD.org</email>"> - -<!ENTITY a.jmz "Jean-Marc Zucconi <email>jmz@FreeBSD.org</email>"> - -<!ENTITY a.joerg "Jörg Wunsch <email>joerg@FreeBSD.org</email>"> - -<!ENTITY a.john "John Cavanaugh <email>john@FreeBSD.org</email>"> - -<!ENTITY a.jraynard "James Raynard <email>jraynard@FreeBSD.org</email>"> - -<!ENTITY a.jseger "Justin Seger <email>jseger@FreeBSD.org</email>"> - -<!ENTITY a.julian "Julian Elischer <email>julian@FreeBSD.org</email>"> - -<!ENTITY a.jvh "Johannes Helander <email>jvh@FreeBSD.org</email>"> - -<!ENTITY a.karl "Karl Strickland <email>karl@FreeBSD.org</email>"> - -<!ENTITY a.kato "Takenori KATO <email>kato@FreeBSD.org</email>"> - -<!ENTITY a.kelly "Sean Kelly <email>kelly@plutotech.com</email>"> - -<!ENTITY a.ken "Kenneth D. Merry <email>ken@FreeBSD.org</email>"> - -<!ENTITY a.kevlo "Kevin Lo <email>kevlo@FreeBSD.org</email>"> - -<!ENTITY a.kjc "Kenjiro Cho <email>kjc@FreeBSD.org</email>"> - -<!ENTITY a.kris "Kris Kennaway <email>kris@FreeBSD.org</email>"> - -<!ENTITY a.kuriyama "Jun Kuriyama <email>kuriyama@FreeBSD.org</email>"> - -<!ENTITY a.lars "Lars Fredriksen <email>lars@FreeBSD.org</email>"> - -<!ENTITY a.lile "Larry Lile <email>lile@FreeBSD.org</email>"> - -<!ENTITY a.ljo "L Jonas Olsson <email>ljo@FreeBSD.org</email>"> - -<!ENTITY a.luoqi "Luoqi Chen <email>luoqi@FreeBSD.org</email>"> - -<!ENTITY a.marcel "Marcel Moolenaar <email>marcel@FreeBSD.org</email>"> - -<!ENTITY a.markm "Mark Murray <email>markm@FreeBSD.org</email>"> - -<!ENTITY a.martin "Martin Renters <email>martin@FreeBSD.org</email>"> - -<!ENTITY a.max "Masafumi NAKANE <email>max@FreeBSD.org</email>"> - -<!ENTITY a.mayo "Mark Mayo <email>mark@vmunix.com</email>"> - -<!ENTITY a.mbarkah "Ade Barkah <email>mbarkah@FreeBSD.org</email>"> - -<!ENTITY a.mckay "Stephen McKay <email>mckay@FreeBSD.org</email>"> - -<!ENTITY a.mckusick "Kirk McKusick <email>mckusick@FreeBSD.org</email>"> - -<!ENTITY a.md "Mark Dapoz <email>md@bsc.no</email>"> - -<!ENTITY a.mdodd "Matthew N. Dodd <email>winter@jurai.net</email>"> - -<!ENTITY a.mharo "Michael Haro <email>mharo@FreeBSD.org</email>"> - -<!ENTITY a.mjacob "Matthew Jacob <email>mjacob@FreeBSD.org</email>"> - -<!ENTITY a.mks "Mike Spengler <email>mks@FreeBSD.org</email>"> - -<!ENTITY a.motoyuki "Motoyuki Konno <email>motoyuki@FreeBSD.org</email>"> - -<!ENTITY a.mph "Matthew Hunt <email>mph@FreeBSD.org</email>"> - -<!ENTITY a.mpp "Mike Pritchard <email>mpp@FreeBSD.org</email>"> - -<!ENTITY a.msmith "Michael Smith <email>msmith@FreeBSD.org</email>"> - -<!ENTITY a.nate "Nate Williams <email>nate@FreeBSD.org</email>"> - -<!ENTITY a.nectar "Jacques Vidrine <email>nectar@FreeBSD.org</email>"> - -<!ENTITY a.newton "Mark Newton <email>newton@FreeBSD.org</email>"> - -<!ENTITY a.nhibma "Nick Hibma <email>n_hibma@FreeBSD.org</email>"> - -<!ENTITY a.nik "Nik Clayton <email>nik@FreeBSD.org</email>"> - -<!ENTITY a.nsayer "Nick Sayer <email>nsayer@FreeBSD.org</email>"> - -<!ENTITY a.nsj "Nate Johnson <email>nsj@FreeBSD.org</email>"> - -<!ENTITY a.nyan "Yoshihiro Takahashi <email>nyan@FreeBSD.org</email>"> - -<!ENTITY a.obrien "David O'Brien <email>obrien@FreeBSD.org</email>"> - -<!ENTITY a.olah "Andras Olah <email>olah@FreeBSD.org</email>"> - -<!ENTITY a.opsys "Chris Watson <email>opsys@open-systems.net</email>"> - -<!ENTITY a.paul "Paul Richards <email>paul@FreeBSD.org</email>"> - -<!ENTITY a.pb "Pierre Beyssac <email>pb@fasterix.freenix.org</email>"> - -<!ENTITY a.pds "Peter da Silva <email>pds@FreeBSD.org</email>"> - -<!ENTITY a.peter "Peter Wemm <email>peter@FreeBSD.org</email>"> - -<!ENTITY a.phk "Poul-Henning Kamp <email>phk@FreeBSD.org</email>"> - -<!ENTITY a.pjc "Peter Childs <email>pjchilds@imforei.apana.org.au</email>"> - -<!ENTITY a.proven "Chris Provenzano <email>proven@FreeBSD.org</email>"> - -<!ENTITY a.pst "Paul Traina <email>pst@FreeBSD.org</email>"> - -<!ENTITY a.rgrimes "Rodney Grimes <email>rgrimes@FreeBSD.org</email>"> - -<!ENTITY a.rhuff "Robert Huff <email>rhuff@cybercom.net</email>"> - -<!ENTITY a.ricardag "Ricardo AG <email>ricardag@ag.com.br</email>"> - -<!ENTITY a.rich "Rich Murphey <email>rich@FreeBSD.org</email>"> - -<!ENTITY a.rnordier "Robert Nordier <email>rnordier@FreeBSD.org</email>"> - -<!ENTITY a.roberto "Ollivier Robert <email>roberto@FreeBSD.org</email>"> - -<!ENTITY a.rse "Ralf S. Engelschall <email>rse@FreeBSD.org</email>"> - -<!ENTITY a.ru "Ruslan Ermilov <email>ru@FreeBSD.org</email>"> - -<!ENTITY a.sada "Kenji SADA <email>sada@FreeBSD.org</email>"> - -<!ENTITY a.scrappy "Marc G. Fournier <email>scrappy@FreeBSD.org</email>"> - -<!ENTITY a.se "Stefan Esser <email>se@FreeBSD.org</email>"> - -<!ENTITY a.sef "Sean Eric Fagan <email>sef@FreeBSD.org</email>"> - -<!ENTITY a.sheldonh "Sheldon Hearn <email>sheldonh@FreeBSD.org</email>"> - -<!ENTITY a.shige "Shigeyuki Fukushima <email>shige@FreeBSD.org</email>"> - -<!ENTITY a.shin "Yoshinobu Inoue <email>shin@FreeBSD.org</email>"> - -<!ENTITY a.simokawa "Hidetoshi Shimokawa <email>simokawa@FreeBSD.org</email>"> - -<!ENTITY a.smace "Scott Mace <email>smace@FreeBSD.org</email>"> - -<!ENTITY a.smpatel "Sujal Patel <email>smpatel@FreeBSD.org</email>"> - -<!ENTITY a.sos "Søren Schmidt <email>sos@FreeBSD.org</email>"> - -<!ENTITY a.stark "Gene Stark <email>stark@FreeBSD.org</email>"> - -<!ENTITY a.stb "Stefan Bethke <email>stb@FreeBSD.org</email>"> - -<!ENTITY a.steve "Steve Price <email>steve@FreeBSD.org</email>"> - -<!ENTITY a.sumikawa "Munechika Sumikawa <email>sumikawa@FreeBSD.org</email>"> - -<!ENTITY a.swallace "Steven Wallace <email>swallace@FreeBSD.org</email>"> - -<!ENTITY a.tanimura "Seigo Tanimura <email>tanimura@FreeBSD.org</email>"> - -<!ENTITY a.taoka "Satoshi Taoka <email>taoka@FreeBSD.org</email>"> - -<!ENTITY a.tedm "Ted Mittelstaedt <email>tedm@FreeBSD.org</email>"> - -<!ENTITY a.tegge "Tor Egge <email>tegge@FreeBSD.org</email>"> - -<!ENTITY a.tg "Thomas Gellekum <email>tg@FreeBSD.org</email>"> - -<!ENTITY a.thepish "Peter Hawkins <email>thepish@FreeBSD.org</email>"> - -<!ENTITY a.tom "Tom Hukins <email>tom@FreeBSD.org</email>"> - -<!ENTITY a.torstenb "Torsten Blum <email>torstenb@FreeBSD.org</email>"> - -<!ENTITY a.truckman "Don “Truck” Lewis <email>truckman@FreeBSD.org</email>"> - -<!ENTITY a.ugen "Ugen J.S.Antsilevich <email>ugen@FreeBSD.org</email>"> - -<!ENTITY a.uhclem "Frank Durda IV <email>uhclem@FreeBSD.org</email>"> - -<!ENTITY a.ulf "Ulf Zimmermann <email>ulf@FreeBSD.org</email>"> - -<!ENTITY a.vanilla "Vanilla I. Shu <email>vanilla@FreeBSD.org</email>"> - -<!ENTITY a.wes "Wes Peters <email>wes@FreeBSD.org</email>"> - -<!ENTITY a.whiteside "Don Whiteside <email>whiteside@acm.org</email>"> - -<!ENTITY a.wilko "Wilko Bulte <email>wilko@yedi.iaf.nl</email>"> - -<!ENTITY a.wlloyd "Bill Lloyd <email>wlloyd@mpd.ca</email>"> - -<!ENTITY a.wollman "Garrett Wollman <email>wollman@FreeBSD.org</email>"> - -<!ENTITY a.wosch "Wolfram Schneider <email>wosch@FreeBSD.org</email>"> - -<!ENTITY a.wpaul "Bill Paul <email>wpaul@FreeBSD.org</email>"> - -<!ENTITY a.yokota "Kazutaka YOKOTA <email>yokota@FreeBSD.org</email>"> diff --git a/en/handbook/backups/chapter.sgml b/en/handbook/backups/chapter.sgml deleted file mode 100644 index 2b8fe22c2a..0000000000 --- a/en/handbook/backups/chapter.sgml +++ /dev/null @@ -1,621 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.8 1999-06-15 20:37:38 mpp Exp $ ---> - -<chapter id="backups"> - <title>Backups</title> - - <para>Issues of hardware compatibility are among the most troublesome in the - computer industry today and FreeBSD is by no means immune to trouble. In - this respect, FreeBSD's advantage of being able to run on inexpensive - commodity PC hardware is also its liability when it comes to support for - the amazing variety of components on the market. While it would be - impossible to provide a exhaustive listing of hardware that FreeBSD - supports, this section serves as a catalog of the device drivers included - with FreeBSD and the hardware each drivers supports. Where possible and - appropriate, notes about specific products are included. You may also - want to refer to <link linkend="kernelconfig-config"> the kernel - configuration file</link> section in this handbook for a list of - supported devices.</para> - - <para>As FreeBSD is a volunteer project without a funded testing department, - we depend on you, the user, for much of the information contained in this - catalog. If you have direct experience of hardware that does or does not - work with FreeBSD, please let us know by sending e-mail to the &a.doc;. - Questions about supported hardware should be directed to the &a.questions - (see <link linkend="eresources-mail">Mailing Lists</link> for more - information). When submitting information or asking a question, please - remember to specify exactly what version of FreeBSD you are using and - include as many details of your hardware as possible.</para> - - <sect1> - <title>* What about backups to floppies?</title> - - <para></para> - </sect1> - - <sect1 id="backups-tapebackups"> - <title>Tape Media</title> - - <para>The major tape media are the 4mm, 8mm, QIC, mini-cartridge and - DLT.</para> - - <sect2 id="backups-tapebackups-4mm"> - <title>4mm (DDS: Digital Data Storage)</title> - - <para>4mm tapes are replacing QIC as the workstation backup media of - choice. This trend accelerated greatly when Conner purchased Archive, - a leading manufacturer of QIC drives, and then stopped production of - QIC drives. 4mm drives are small and quiet but do not have the - reputation for reliability that is enjoyed by 8mm drives. The - cartridges are less expensive and smaller (3 x 2 x 0.5 inches, 76 x 51 - x 12 mm) than 8mm cartridges. 4mm, like 8mm, has comparatively short - head life for the same reason, both use helical scan.</para> - - <para>Data thruput on these drives starts ~150kB/s, peaking at ~500kB/s. - Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware - compression, available with most of these drives, approximately - doubles the capacity. Multi-drive tape library units can have 6 - drives in a single cabinet with automatic tape changing. Library - capacities reach 240 GB.</para> - - <para>4mm drives, like 8mm drives, use helical-scan. All the benefits - and drawbacks of helical-scan apply to both 4mm and 8mm drives.</para> - - <para>Tapes should be retired from use after 2,000 passes or 100 full - backups.</para> - </sect2> - - <sect2 id="backups-tapebackups-8mm"> - <title>8mm (Exabyte)</title> - - <para>8mm tapes are the most common SCSI tape drives; they are the best - choice of exchanging tapes. Nearly every site has an exabyte 2 GB 8mm - tape drive. 8mm drives are reliable, convenient and quiet. Cartridges - are inexpensive and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm). - One downside of 8mm tape is relatively short head and tape life due to - the high rate of relative motion of the tape across the heads.</para> - - <para>Data thruput ranges from ~250kB/s to ~500kB/s. Data sizes start - at 300 MB and go up to 7 GB. Hardware compression, available with - most of these drives, approximately doubles the capacity. These - drives are available as single units or multi-drive tape libraries - with 6 drives and 120 tapes in a single cabinet. Tapes are changed - automatically by the unit. Library capacities reach 840+ GB.</para> - - <para>Data is recorded onto the tape using helical-scan, the heads are - positioned at an angle to the media (approximately 6 degrees). The - tape wraps around 270 degrees of the spool that holds the heads. The - spool spins while the tape slides over the spool. The result is a - high density of data and closely packed tracks that angle across the - tape from one edge to the other.</para> - </sect2> - - <sect2 id="backups-tapebackups-qic"> - <title>QIC</title> - - <para>QIC-150 tapes and drives are, perhaps, the most common tape drive - and media around. QIC tape drives are the least expensive "serious" - backup drives. The downside is the cost of media. QIC tapes are - expensive compared to 8mm or 4mm tapes, up to 5 times the price per GB - data storage. But, if your needs can be satisfied with a half-dozen - tapes, QIC may be the correct choice. QIC is the - <emphasis>most</emphasis> common tape drive. Every site has a QIC - drive of some density or another. Therein lies the rub, QIC has a - large number of densities on physically similar (sometimes identical) - tapes. QIC drives are not quiet. These drives audibly seek before - they begin to record data and are clearly audible whenever reading, - writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x - 10.2 x 1.7 mm). <link - linkend="backups-tapebackups-mini">Mini-cartridges</link>, which - also use 1/4" wide tape are discussed separately. Tape libraries and - changers are not available.</para> - - <para>Data thruput ranges from ~150kB/s to ~500kB/s. Data capacity - ranges from 40 MB to 15 GB. Hardware compression is available on many - of the newer QIC drives. QIC drives are less frequently installed; - they are being supplanted by DAT drives.</para> - - <para>Data is recorded onto the tape in tracks. The tracks run along - the long axis of the tape media from one end to the other. The number - of tracks, and therefore the width of a track, varies with the tape's - capacity. Most if not all newer drives provide backward-compatibility - at least for reading (but often also for writing). QIC has a good - reputation regarding the safety of the data (the mechanics are simpler - and more robust than for helical scan drives).</para> - - <para>Tapes should be retired from use after 5,000 backups.</para> - </sect2> - - <sect2 id="backups-tapebackups-mini"> - <title>* Mini-Cartridge</title> - - <para></para> - </sect2> - - <sect2 id="backups-tapebackups-dlt"> - <title>DLT</title> - - <para>DLT has the fastest data transfer rate of all the drive types - listed here. The 1/2" (12.5mm) tape is contained in a single spool - cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm). The cartridge has a - swinging gate along one entire side of the cartridge. The drive - mechanism opens this gate to extract the tape leader. The tape leader - has an oval hole in it which the drive uses to "hook" the tape. The - take-up spool is located inside the tape drive. All the other tape - cartridges listed here (9 track tapes are the only exception) have - both the supply and take-up spools located inside the tape cartridge - itself.</para> - - <para>Data thruput is approximately 1.5MB/s, three times the thruput of - 4mm, 8mm, or QIC tape drives. Data capacities range from 10GB to 20GB - for a single drive. Drives are available in both multi-tape changers - and multi-tape, multi-drive tape libraries containing from 5 to 900 - tapes over 1 to 20 drives, providing from 50GB to 9TB of - storage.</para> - - <para>Data is recorded onto the tape in tracks parallel to the direction - of travel (just like QIC tapes). Two tracks are written at once. - Read/write head lifetimes are relatively long; once the tape stops - moving, there is no relative motion between the heads and the - tape.</para> - </sect2> - - <sect2> - <title>Using a new tape for the first time</title> - - <para>The first time that you try to read or write a new, completely - blank tape, the operation will fail. The console messages should be - similar to:</para> - - <screen>sa0(ncr1:4:0): NOT READY asc:4,1 -sa0(ncr1:4:0): Logical unit is in process of becoming ready</screen> - - <para>The tape does not contain an Identifier Block (block number 0). - All QIC tape drives since the adoption of QIC-525 standard write an - Identifier Block to the tape. There are two solutions:</para> - - <para><command>mt fsf 1</command> causes the tape drive to write an - Identifier Block to the tape.</para> - - <para>Use the front panel button to eject the tape.</para> - - <para>Re-insert the tape and &man.dump.8; data to the tape.</para> - - <para>&man.dump.8; will report <literal>DUMP: End of tape - detected</literal> and the console will show: <literal>HARDWARE - FAILURE info:280 asc:80,96</literal></para> - - <para>rewind the tape using: <command>mt rewind</command></para> - - <para>Subsequent tape operations are successful.</para> - </sect2> - </sect1> - - <sect1 id="backup-programs"> - <title>Backup Programs</title> - - <para>The three major programs are - &man.dump.8;, - &man.tar.1;, - and - &man.cpio.1;.</para> - - <sect2> - <title>Dump and Restore</title> - - <para>&man.dump.8; and &man.restore.8; are the traditional Unix backup - programs. They operate on the drive as a collection of disk blocks, - below the abstractions of files, links and directories that are - created by the filesystems. &man.dump.8; backs up devices, entire - filesystems, not parts of a filesystem and not directory trees that - span more than one filesystem, using either soft links &man.ln.1; or - mounting one filesystem onto another. &man.dump.8; does not write - files and directories to tape, but rather writes the data blocks that - are the building blocks of files and directories. &man.dump.8; has - quirks that remain from its early days in Version 6 of ATT Unix (circa - 1975). The default parameters are suitable for 9-track tapes (6250 - bpi), not the high-density media available today (up to 62,182 ftpi). - These defaults must be overridden on the command line to utilize the - capacity of current tape drives.</para> - - <para>&man.rdump.8; and &man.rrestore.8; backup data across the network - to a tape drive attached to another computer. Both programs rely upon - &man.rcmd.3; and &man.ruserok.3; to access the remote tape drive. - Therefore, the user performing the backup must have - <literal>rhosts</literal> access to the remote computer. The - arguments to &man.rdump.8; and &man.rrestore.8; must suitable to use - on the remote computer. (e.g. When <command>rdump</command>'ing from - a FreeBSD computer to an Exabyte tape drive connected to a Sun called - <hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000 13000 - 126 komodo:/dev/nrsa8 /dev/rda0a 2>&1</command>) Beware: there - are security implications to allowing <literal>rhosts</literal> - commands. Evaluate your situation carefully.</para> - </sect2> - - <sect2> - <title>Tar</title> - - <para>&man.tar.1; also dates back to Version 6 of ATT Unix (circa 1975). - &man.tar.1; operates in cooperation with the filesystem; &man.tar.1; - writes files and directories to tape. &man.tar.1; does not support the - full range of options that are available from &man.cpio.1;, but - &man.tar.1; does not require the unusual command pipeline that - &man.cpio.1; uses.</para> - - <para>Most versions of &man.tar.1; do not support backups across the - network. The GNU version of &man.tar.1;, which FreeBSD utilizes, - supports remote devices using the same syntax as &man.rdump.8;. To - &man.tar.1; to an Exabyte tape drive connected to a Sun called - <hostid>komodo</hostid>, use: <command>/usr/bin/tar cf - komodo:/dev/nrsa8 . 2>&1</command>. For versions without remote - device support, you can use a pipeline and &man.rsh.1; to send the - data to a remote tape drive. (XXX add an example command)</para> - </sect2> - - <sect2> - <title>Cpio</title> - - <para>&man.cpio.1; is the original Unix file interchange tape program - for magnetic media. &man.cpio.1; has options (among many others) to - perform byte-swapping, write a number of different archives format, - and pipe the data to other programs. This last feature makes - &man.cpio.1; and excellent choice for installation media. - &man.cpio.1; does not know how to walk the directory tree and a list - of files must be provided through <filename>stdin</filename>.</para> - - <para>&man.cpio.1; does not support backups across the network. You can - use a pipeline and &man.rsh.1; to send the data to a remote tape - drive. (XXX add an example command)</para> - </sect2> - - <sect2> - <title>Pax</title> - - <para>&man.pax.1; is IEEE/POSIX's answer to &man.tar.1; and - &man.cpio.1;. Over the years the various versions of &man.tar.1; - and &man.cpio.1; have gotten slightly incompatible. So rather than - fight it out to fully standardize them, POSIX created a new archive - utility. &man.pax.1; attempts to read and write many of the various - &man.cpio.1; and &man.tar.1; formats, plus new formats of its own. - Its command set more resembles &man.cpio.1; than &man.tar.1;.</para> - </sect2> - - <sect2 id="backups-programs-amanda"> - <title>Amanda</title> - - <para><ulink url="../ports/misc.html#amanda-2.4.0">Amanda</ulink> - (Advanced Maryland Network Disk Archiver) is a client/server backup - system, rather than a single program. An Amanda server will backup to - a single tape drive any number of computers that have Amanda clients - and network communications with the Amanda server. A common problem - at locations with a number of large disks is the length of time - required to backup to data directly to tape exceeds the amount of time - available for the task. Amanda solves this problem. Amanda can use a - "holding disk" to backup several filesystems at the same time. Amanda - creates "archive sets": a group of tapes used over a period of time to - create full backups of all the filesystems listed in Amanda's - configuration file. The "archive set" also contains nightly - incremental (or differential) backups of all the filesystems. - Restoring a damaged filesystem requires the most recent full backup - and the incremental backups.</para> - - <para>The configuration file provides fine control backups and the - network traffic that Amanda generates. Amanda will use any of the - above backup programs to write the data to tape. Amanda is available - as either a port or a package, it is not installed by default.</para> - </sect2> - - <sect2> - <title>Do nothing</title> - - <para>“Do nothing” is not a computer program, but it is the - most widely used backup strategy. There are no initial costs. There - is no backup schedule to follow. Just say no. If something happens - to your data, grin and bear it!</para> - - <para>If your time and your data is worth little to nothing, then - “Do nothing” is the most suitable backup program for your - computer. But beware, Unix is a useful tool, you may find that within - six months you have a collection of files that are valuable to - you.</para> - - <para>“Do nothing” is the correct backup method for - <filename>/usr/obj</filename> and other directory trees that can be - exactly recreated by your computer. An example is the files that - comprise these handbook pages-they have been generated from - <acronym>SGML</acronym> input files. Creating backups of these - <acronym>HTML</acronym> files is not necessary. The - <acronym>SGML</acronym> source files are backed up regularly.</para> - </sect2> - - <sect2> - <title>Which Backup Program is Best?</title> - - <para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D. Zwicky - torture tested all the backup programs discussed here. The clear - choice for preserving all your data and all the peculiarities of Unix - filesystems is &man.dump.8;. Elizabeth created filesystems containing - a large variety of unusual conditions (and some not so unusual ones) - and tested each program by do a backup and restore of that - filesystems. The peculiarities included: files with holes, files with - holes and a block of nulls, files with funny characters in their - names, unreadable and unwritable files, devices, files that change - size during the backup, files that are created/deleted during the - backup and more. She presented the results at LISA V in Oct. 1991. - See <ulink - url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing - Backup and Archive Programs</ulink>.</para> - </sect2> - - <sect2> - <title>Emergency Restore Procedure</title> - - <sect3> - <title>Before the Disaster</title> - - <para>There are only four steps that you need to perform in - preparation for any disaster that may occur.</para> - - <para>First, print the disklabel from each of your disks - (<command>e.g. disklabel da0 | lpr</command>), your filesystem table - (<command>/etc/fstab</command>) and all boot messages, two copies of - each.</para> - - <para>Second, determine that the boot and fixit floppies - (<filename>boot.flp</filename> and <filename>fixit.flp</filename>) - have all your devices. The easiest way to check is to reboot your - machine with the boot floppy in the floppy drive and check the boot - messages. If all your devices are listed and functional, skip on to - step three.</para> - - <para>Otherwise, you have to create two custom bootable floppies which - has a kernel that can mount your all of your disks and access your - tape drive. These floppies must contain: - &man.fdisk.8;, &man.disklabel.8;, &man.newfs.8;, &man.mount.8;, and - whichever backup program you use. These programs must be statically - linked. If you use &man.dump.8;, the floppy must contain - &man.restore.8;.</para> - - <para>Third, create backup tapes regularly. Any changes that you make - after your last backup may be irretrievably lost. Write-protect the - backup tapes.</para> - - <para>Fourth, test the floppies (either <filename>boot.flp</filename> - and <filename>fixit.flp</filename> or the two custom bootable - floppies you made in step two.) and backup tapes. Make notes of the - procedure. Store these notes with the bootable floppy, the - printouts and the backup tapes. You will be so distraught when - restoring that the notes may prevent you from destroying your backup - tapes (How? In place of <command>tar xvf /dev/rsa0</command>, you - might accidently type <command>tar cvf /dev/rsa0</command> and - over-write your backup tape).</para> - - <para>For an added measure of security, make bootable floppies and two - backup tapes each time. Store one of each at a remote location. A - remote location is NOT the basement of the same office building. A - number of firms in the World Trade Center learned this lesson the - hard way. A remote location should be physically separated from - your computers and disk drives by a significant distance.</para> - - <para>An example script for creating a bootable floppy:</para> - - <programlisting> -<![ CDATA [#!/bin/sh -# -# create a restore floppy -# -# format the floppy -# -PATH=/bin:/sbin:/usr/sbin:/usr/bin - -fdformat -q fd0 -if [ $? -ne 0 ] -then - echo "Bad floppy, please use a new one" - exit 1 -fi - -# place boot blocks on the floppy -# -disklabel -w -B /dev/rfd0c fd1440 - -# -# newfs the one and only partition -# -newfs -t 2 -u 18 -l 1 -c 40 -i 5120 -m 5 -o space /dev/rfd0a - -# -# mount the new floppy -# -mount /dev/fd0a /mnt - -# -# create required directories -# -mkdir /mnt/dev -mkdir /mnt/bin -mkdir /mnt/sbin -mkdir /mnt/etc -mkdir /mnt/root -mkdir /mnt/mnt # for the root partition -mkdir /mnt/tmp -mkdir /mnt/var - -# -# populate the directories -# -if [ ! -x /sys/compile/MINI/kernel ] -then - cat << EOM -The MINI kernel does not exist, please create one. -Here is an example config file: -# -# MINI -- A kernel to get FreeBSD on onto a disk. -# -machine "i386" -cpu "I486_CPU" -ident MINI -maxusers 5 - -options INET # needed for _tcp _icmpstat _ipstat - # _udpstat _tcpstat _udb -options FFS #Berkeley Fast File System -options FAT_CURSOR #block cursor in syscons or pccons -options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device -options NCONS=2 #1 virtual consoles -options USERCONFIG #Allow user configuration with -c XXX - -config kernel root on da0 swap on da0 and da1 dumps on da0 - -controller isa0 -controller pci0 - -controller fdc0 at isa? port "IO_FD1" bio irq 6 drq 2 vector fdintr -disk fd0 at fdc0 drive 0 - -controller ncr0 - -controller scbus0 - -device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr -device npx0 at isa? port "IO_NPX" irq 13 vector npxintr - -device da0 -device da1 -device da2 - -device sa0 - -pseudo-device loop # required by INET -pseudo-device gzip # Exec gzipped a.out's -EOM - exit 1 -fi - -cp -f /sys/compile/MINI/kernel /mnt - -gzip -c -best /sbin/init > /mnt/sbin/init -gzip -c -best /sbin/fsck > /mnt/sbin/fsck -gzip -c -best /sbin/mount > /mnt/sbin/mount -gzip -c -best /sbin/halt > /mnt/sbin/halt -gzip -c -best /sbin/restore > /mnt/sbin/restore - -gzip -c -best /bin/sh > /mnt/bin/sh -gzip -c -best /bin/sync > /mnt/bin/sync - -cp /root/.profile /mnt/root - -cp -f /dev/MAKEDEV /mnt/dev -chmod 755 /mnt/dev/MAKEDEV - -chmod 500 /mnt/sbin/init -chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt -chmod 555 /mnt/bin/sh /mnt/bin/sync -chmod 6555 /mnt/sbin/restore - -# -# create the devices nodes -# -cd /mnt/dev -./MAKEDEV std -./MAKEDEV da0 -./MAKEDEV da1 -./MAKEDEV da2 -./MAKEDEV sa0 -./MAKEDEV pty0 -cd / - -# -# create minimum filesystem table -# -cat > /mnt/etc/fstab <<EOM -/dev/fd0a / ufs rw 1 1 -EOM - -# -# create minimum passwd file -# -cat > /mnt/etc/passwd <<EOM -root:*:0:0:Charlie &:/root:/bin/sh -EOM - -cat > /mnt/etc/master.passwd <<EOM -root::0:0::0:0:Charlie &:/root:/bin/sh -EOM - -chmod 600 /mnt/etc/master.passwd -chmod 644 /mnt/etc/passwd -/usr/sbin/pwd_mkdb -d/mnt/etc /mnt/etc/master.passwd - -# -# umount the floppy and inform the user -# -/sbin/umount /mnt]]></programlisting> - </sect3> - - <sect3> - <title>After the Disaster</title> - - <para>The key question is: did your hardware survive? You have been - doing regular backups so there is no need to worry about the - software.</para> - - <para>If the hardware has been damaged. First, replace those parts - that have been damaged.</para> - - <para>If your hardware is okay, check your floppies. If you are using - a custom boot floppy, boot single-user (type <literal>-s</literal> - at the <prompt>boot:</prompt> prompt). Skip the following - paragraph.</para> - - <para>If you are using the <filename>boot.flp</filename> and - <filename>fixit.flp</filename> floppies, keep reading. Insert the - <filename>boot.flp</filename> floppy in the first floppy drive and - boot the computer. The original install menu will be displayed on - the screen. Select the <literal>Fixit--Repair mode with CDROM or - floppy.</literal> option. Insert the - <filename>fixit.flp</filename> when prompted. - <command>restore</command> and the other programs that you need are - located in <filename>/mnt2/stand</filename>.</para> - - <para>Recover each filesystem separately.</para> - - <para>Try to &man.mount.8; (e.g. <command>mount /dev/da0a - /mnt</command>) the root partition of your first disk. If the - disklabel was damaged, use &man.disklabel.8; to re-partition and - label the disk to match the label that your printed and saved. Use - &man.newfs.8; to re-create the filesystems. Re-mount the root - partition of the floppy read-write (<command>mount -u -o rw - /mnt</command>). Use your backup program and backup tapes to - recover the data for this filesystem (e.g. <command>restore vrf - /dev/sa0</command>). Unmount the filesystem (e.g. <command>umount - /mnt</command>) Repeat for each filesystem that was - damaged.</para> - - <para>Once your system is running, backup your data onto new tapes. - Whatever caused the crash or data loss may strike again. An another - hour spent now, may save you from further distress later.</para> - </sect3> - - <sect3> - <title>* I did not prepare for the Disaster, What Now?</title> - - <para></para> - </sect3> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> diff --git a/en/handbook/basics/chapter.sgml b/en/handbook/basics/chapter.sgml deleted file mode 100644 index d0563703f7..0000000000 --- a/en/handbook/basics/chapter.sgml +++ /dev/null @@ -1,139 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.9 1999-04-08 21:30:16 nik Exp $ ---> - -<chapter id="basics"> - <title>Unix Basics</title> - - <sect1 id="basics-man"> - <title>The Online Manual</title> - - <para>The most comprehensive documentation on FreeBSD is in the form of - <emphasis>man pages</emphasis>. Nearly every program on the system - comes with a short reference manual explaining the basic operation and - various arguments. These manuals can be view with the - <command>man</command> command. Use of the <command>man</command> - command is simple:</para> - - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - - <para><replaceable>command</replaceable> is the name of the command you - wish to learn about. For example, to learn more about - <command>ls</command> command type:</para> - - <screen>&prompt.user; <userinput>man ls</userinput></screen> - - <para>The online manual is divided up into numbered sections:</para> - - <orderedlist> - <listitem> - <para>User commands</para> - </listitem> - - <listitem> - <para>System calls and error numbers</para> - </listitem> - - <listitem> - <para>Functions in the C libraries</para> - </listitem> - - <listitem> - <para>Device drivers</para> - </listitem> - - <listitem> - <para>File formats</para> - </listitem> - - <listitem> - <para>Games and other diversions</para> - </listitem> - - <listitem> - <para>Miscellaneous information</para> - </listitem> - - <listitem> - <para>System maintenance and operation commands</para> - </listitem> - - <listitem> - <para>Kernel developers</para> - </listitem> - </orderedlist> - - <para>In some cases, the same topic may appear in more than one section of - the on-line manual. For example, there is a <command>chmod</command> - user command and a <function>chmod()</function> system call. In this - case, you can tell the <command>man</command> command which one you want - by specifying the section:</para> - - <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen> - - <para>This will display the manual page for the user command - <command>chmod</command>. References to a particular section of the - on-line manual are traditionally placed in parenthesis in written - documentation, so &man.chmod.1; refers to the - <command>chmod</command> user command and &man.chmod.2; refers to the - system call.</para> - - <para>This is fine if you know the name of the command and simply wish to - know how to use it, but what if you cannot recall the command name? You - can use <command>man</command> to search for keywords in the command - <emphasis>descriptions</emphasis> by using the <option>-k</option> - switch:</para> - - <screen>&prompt.user; <userinput>man -k mail</userinput></screen> - - <para>With this command you will be presented with a list of commands that - have the keyword “mail” in their descriptions. This is - actually functionally equivalent to using the <command>apropos</command> - command.</para> - - <para>So, you are looking at all those fancy commands in - <filename>/usr/bin</filename> but do not even have the faintest idea - what most of them actually do? Simply do a - - <screen>&prompt.user; <userinput>cd /usr/bin; man -f *</userinput></screen> - - or - - <screen>&prompt.user; <userinput>cd /usr/bin; whatis *</userinput></screen> - - which does the same thing.</para> - </sect1> - - <sect1 id="basics-info"> - <title>GNU Info Files</title> - - <para>FreeBSD includes many applications and utilities produced by the - Free Software Foundation (FSF). In addition to man pages, these - programs come with more extensive hypertext documents called - “info” files which can be viewed with the - <command>info</command> command or, if you installed - <command>emacs</command>, the info mode of - <command>emacs</command>.</para> - - <para>To use the &man.info.1; command, simply type:</para> - - <screen>&prompt.user; <userinput>info</userinput></screen> - - <para>For a brief introduction, type <userinput>h</userinput>. For a - quick command reference, type <userinput>?</userinput>.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/bibliography/chapter.sgml b/en/handbook/bibliography/chapter.sgml deleted file mode 100644 index 3666b3bc11..0000000000 --- a/en/handbook/bibliography/chapter.sgml +++ /dev/null @@ -1,478 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.13 1999-08-05 20:48:08 nik Exp $ ---> - -<chapter id="bibliography"> - <title>Bibliography</title> - - <para>While the manual pages provide the definitive reference for individual - pieces of the FreeBSD operating system, they are notorious for not - illustrating how to put the pieces together to make the whole operating - system run smoothly. For this, there is no substitute for a good book on - UNIX system administration and a good users' manual.</para> - - <sect1> - <title>Books & Magazines Specific to FreeBSD</title> - - <para><emphasis>International books & - Magazines:</emphasis></para> - - <itemizedlist> - <listitem> - <para><ulink - URL="http://freebsd.csie.nctu.edu.tw/~jdli/book.html">Using - FreeBSD</ulink> (in Chinese).</para> - </listitem> - - <listitem> - <para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA System - Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para> - </listitem> - - <listitem> - <para>FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2 - C3055 P2400E.</para> - </listitem> - - <listitem> - <para><ulink - URL="http://www.shoeisha.co.jp/pc/index/shinkan/97_05_06.htm">Complete Introduction to FreeBSD</ulink> (in Japanese), published by <ulink URL="http://www.shoeisha.co.jp/">Shoeisha Co., Ltd</ulink>. ISBN 4-88135-473-6 P3600E.</para> - </listitem> - - <listitem> - <para><ulink - URL="http://www.ascii.co.jp/pb/book1/shinkan/detail/1322785.html">Personal UNIX Starter Kit FreeBSD</ulink> (in Japanese), published by <ulink URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN 4-7561-1733-3 P3000E.</para> - </listitem> - - <listitem> - <para>FreeBSD Handbook (Japanese translation), published by <ulink - URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN 4-7561-1580-2 - P3800E.</para> - </listitem> - - <listitem> - <para>FreeBSD mit Methode (in German), published by Computer und - Literatur Verlag/Vertrieb Hanser, 1998. ISBN 3-932311-31-0.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.pc.mycom.co.uk/FreeBSD/install-manual.html">FreeBSD Install and Utilization Manual</ulink> (in Japanese), published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi Communications Inc.</ulink>.</para> - </listitem> - </itemizedlist> - - <para><emphasis>English language books & Magazines:</emphasis></para> - - <itemizedlist> - <listitem> - <para><ulink - URL="http://www.cdrom.com/titles/freebsd/bsdbook2.phtml">The - Complete FreeBSD</ulink>, published by <ulink - URL="http://www.cdrom.com">Walnut Creek CDROM</ulink>.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Users' Guides</title> - - <itemizedlist> - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - User's Reference Manual</emphasis>. O'Reilly & Associates, - Inc., 1994. ISBN 1-56592-075-9</para> - </listitem> - - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - User's Supplementary Documents</emphasis>. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-076-7</para> - </listitem> - - <listitem> - <para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly & - Associates, Inc., 1990. ISBN 093717520X</para> - </listitem> - - <listitem> - <para>Mui, Linda. <emphasis>What You Need To Know When You Can't Find - Your UNIX System Administrator</emphasis>. O'Reilly & - Associates, Inc., 1995. ISBN 1-56592-104-6</para> - </listitem> - - <listitem> - <para><ulink URL="http://www-wks.acs.ohio-state.edu/">Ohio State - University</ulink> has written a <ulink - URL="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX - Introductory Course</ulink> which is available online in HTML and - postscript format.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, Japan - FreeBSD Users Group</ulink>. <ulink - url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD User's - Reference Manual</ulink> (Japanese translation). <ulink - url="http://www.pc.mycom.co.jp/">Mainichi Communications - Inc.</ulink>, 1998. ISBN4-8399-0088-4 P3800E.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Administrators' Guides</title> - - <itemizedlist> - <listitem> - <para>Albitz, Paul and Liu, Cricket. <emphasis>DNS and - BIND</emphasis>, 2nd Ed. O'Reilly & Associates, Inc., 1997. - ISBN 1-56592-236-0</para> - </listitem> - - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - System Manager's Manual</emphasis>. O'Reilly & Associates, - Inc., 1994. ISBN 1-56592-080-5</para> - </listitem> - - <listitem> - <para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd Ed. - O'Reilly & Associates, Inc., 1997. ISBN 1-56592-222-0</para> - </listitem> - - <listitem> - <para>Frisch, Æleen. <emphasis>Essential System - Administration</emphasis>, 2nd Ed. O'Reilly & Associates, - Inc., 1995. ISBN 1-56592-127-5</para> - </listitem> - - <listitem> - <para>Hunt, Craig. <emphasis>TCP/IP Network - Administration</emphasis>. O'Reilly & Associates, Inc., 1992. - ISBN 0-937175-82-X</para> - </listitem> - - <listitem> - <para>Nemeth, Evi. <emphasis>UNIX System Administration - Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. ISBN - 0131510517</para> - </listitem> - - <listitem> - <para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis> O'Reilly - & Associates, Inc., 1991. ISBN 0-937175-75-7</para> - </listitem> - - <listitem> - <para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, Japan - FreeBSD Users Group</ulink>. <ulink - url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD System - Administrator's Manual</ulink> (Japanese translation). <ulink - url="http://www.pc.mycom.co.jp/">Mainichi Communications - Inc.</ulink>, 1998. ISBN4-8399-0109-0 P3300E.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Programmers' Guides</title> - - <itemizedlist> - <listitem> - <para>Asente, Paul. <emphasis>X Window System Toolkit</emphasis>. - Digital Press. ISBN 1-55558-051-3</para> - </listitem> - - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - Programmer's Reference Manual</emphasis>. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-078-3</para> - </listitem> - - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - Programmer's Supplementary Documents</emphasis>. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-079-1</para> - </listitem> - - <listitem> - <para>Harbison, Samuel P. and Steele, Guy L. Jr. <emphasis>C: A - Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995. - ISBN 0-13-326224-3</para> - </listitem> - - <listitem> - <para>Kernighan, Brian and Dennis M. Ritchie. <emphasis>The C - Programming Language.</emphasis>. PTR Prentice Hall, 1988. - ISBN 0-13-110362-9</para> - </listitem> - - <listitem> - <para>Lehey, Greg. <emphasis>Porting UNIX Software</emphasis>. - O'Reilly & Associates, Inc., 1995. ISBN 1-56592-126-7</para> - </listitem> - - <listitem> - <para>Plauger, P. J. <emphasis>The Standard C Library</emphasis>. - Prentice Hall, 1992. ISBN 0-13-131509-9</para> - </listitem> - - <listitem> - <para>Stevens, W. Richard. <emphasis>Advanced Programming in the UNIX - Environment</emphasis>. Reading, Mass. : Addison-Wesley, 1992 - ISBN 0-201-56317-7</para> - </listitem> - - <listitem> - <para>Stevens, W. Richard. <emphasis>UNIX Network - Programming</emphasis>. 2nd Ed, PTR Prentice Hall, 1998. ISBN - 0-13-490012-X</para> - </listitem> - - <listitem> - <para>Wells, Bill. “Writing Serial Drivers for UNIX”. - <emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December 1994. - pp68-71, 97-99.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Operating System Internals</title> - - <itemizedlist> - <listitem> - <para>Andleigh, Prabhat K. <emphasis>UNIX System - Architecture</emphasis>. Prentice-Hall, Inc., 1990. ISBN - 0-13-949843-5</para> - </listitem> - - <listitem> - <para>Jolitz, William. “Porting UNIX to the 386”. - <emphasis>Dr. Dobb's Journal</emphasis>. January 1991-July - 1992.</para> - </listitem> - - <listitem> - <para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and - John Quarterman <emphasis>The Design and Implementation of the - 4.3BSD UNIX Operating System</emphasis>. Reading, Mass. : - Addison-Wesley, 1989. ISBN 0-201-06196-1</para> - </listitem> - - <listitem> - <para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The Design - and Implementation of the 4.3BSD UNIX Operating System: Answer - Book</emphasis>. Reading, Mass. : Addison-Wesley, 1991. ISBN - 0-201-54629-9</para> - </listitem> - - <listitem> - <para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and - John Quarterman. <emphasis>The Design and Implementation of the - 4.4BSD Operating System</emphasis>. Reading, Mass. : - Addison-Wesley, 1996. ISBN 0-201-54979-4</para> - </listitem> - - <listitem> - <para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 1: - The Protocols</emphasis>. Reading, Mass. : Addison-Wesley, - 1996. ISBN 0-201-63346-9</para> - </listitem> - - <listitem> - <para>Schimmel, Curt. <emphasis>Unix Systems for Modern - Architectures</emphasis>. Reading, Mass. : Addison-Wesley, 1994. - ISBN 0-201-63338-8</para> - </listitem> - - <listitem> - <para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 3: - TCP for Transactions, HTTP, NNTP and the UNIX Domain - Protocols</emphasis>. Reading, Mass. : Addison-Wesley, 1996. - ISBN 0-201-63495-3</para> - </listitem> - - <listitem> - <para>Vahalia, Uresh. <emphasis>UNIX Internals -- The New - Frontiers</emphasis>. Prentice Hall, 1996. ISBN - 0-13-101908-2</para> - </listitem> - - <listitem> - <para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP - Illustrated, Volume 2: The Implementation</emphasis>. Reading, - Mass. : Addison-Wesley, 1995. ISBN 0-201-63354-X</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Security Reference</title> - - <itemizedlist> - <listitem> - <para>Cheswick, William R. and Steven M. Bellovin. <emphasis>Firewalls - and Internet Security: Repelling the Wily Hacker</emphasis>. - Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-63357-4</para> - </listitem> - - <listitem> - <para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical UNIX - Security</emphasis>. 2nd Ed. O'Reilly & Associates, Inc., - 1996. ISBN 1-56592-148-8</para> - </listitem> - - <listitem> - <para>Garfinkel, Simson. <emphasis>PGP Pretty Good - Privacy</emphasis> O'Reilly & Associates, Inc., 1995. ISBN - 1-56592-098-8</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Hardware Reference</title> - - <itemizedlist> - <listitem> - <para>Anderson, Don and Tom Shanley. <emphasis>Pentium Processor - System Architecture</emphasis>. 2nd Ed. Reading, Mass. : - Addison-Wesley, 1995. ISBN 0-201-40992-5</para> - </listitem> - - <listitem> - <para>Ferraro, Richard F. <emphasis>Programmer's Guide to the EGA, - VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading, Mass. : - Addison-Wesley, 1995. ISBN 0-201-62490-7</para> - </listitem> - - <listitem> - <para>Intel Corporation publishes documentation on their CPUs, - chipsets and standards on their <ulink - url="http://developer.intel.com/">developer web site</ulink>, - usually as PDF files.</para> - </listitem> - - <listitem> - <para>Shanley, Tom. <emphasis>80486 System Architecture</emphasis>. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40994-1</para> - </listitem> - - <listitem> - <para>Shanley, Tom. <emphasis>ISA System Architecture</emphasis>. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40996-8</para> - </listitem> - - <listitem> - <para>Shanley, Tom. <emphasis>PCI System Architecture</emphasis>. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40993-3</para> - </listitem> - - <listitem> - <para>Van Gilluwe, Frank. <emphasis>The Undocumented PC</emphasis>. - Reading, Mass: Addison-Wesley Pub. Co., 1994. ISBN - 0-201-62277-7</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>UNIX History</title> - - <itemizedlist> - <listitem> - <para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed. With - Source Code</emphasis>. ITP Media Group, 1996. ISBN - 1573980137</para> - </listitem> - - <listitem> - <para>Raymond, Eric S. <emphasis>The New Hacker's Dictionary, 3rd - edition</emphasis>. MIT Press, 1996. ISBN - 0-262-68092-0. Also known as the <ulink - URL="http://www.ccil.org/jargon/jargon.html">Jargon - File</ulink></para> - </listitem> - - <listitem> - <para>Salus, Peter H. <emphasis>A quarter century of UNIX</emphasis>. - Addison-Wesley Publishing Company, Inc., 1994. ISBN - 0-201-54777-5</para> - </listitem> - - <listitem> - <para>Simon Garfinkel, Daniel Weise, Steven Strassmann. <emphasis>The - UNIX-HATERS Handbook</emphasis>. IDG Books Worldwide, Inc., - 1994. ISBN 1-56884-203-1</para> - </listitem> - - <listitem> - <para>Don Libes, Sandy Ressler <emphasis>Life with UNIX</emphasis> - — special edition. Prentice-Hall, Inc., 1989. ISBN - 0-13-536657-7</para> - </listitem> - - <listitem> - <para><emphasis>The BSD family tree</emphasis>. 1997. <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink URL="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para> - </listitem> - - <listitem> - <para><emphasis>The BSD Release Announcements collection</emphasis>. - 1997. <ulink - URL="http://www.de.FreeBSD.org/de/ftp/releases/">http://www.de.FreeBSD.org/de/ftp/releases/</ulink></para> - </listitem> - - <listitem> - <para><emphasis>Networked Computer Science Technical Reports - Library</emphasis>. <ulink - URL="http://www.ncstrl.org/">http://www.ncstrl.org/</ulink></para> - </listitem> - - <listitem> - <para><emphasis>Old BSD releases from the Computer Systems Research - group (CSRG)</emphasis>. <ulink - url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>: - The 4CD set covers all BSD versions from 1BSD to 4.4BSD and - 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last - disk holds the final sources plus the SCCS files.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Magazines and Journals</title> - - <itemizedlist> - <listitem> - <para><emphasis>The C/C++ Users Journal</emphasis>. R&D - Publications Inc. ISSN 1075-2838</para> - </listitem> - - <listitem> - <para><emphasis>Sys Admin — The Journal for UNIX System - Administrators</emphasis> Miller Freeman, Inc., ISSN - 1061-2688</para> - </listitem> - </itemizedlist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/chapter.decl b/en/handbook/chapter.decl deleted file mode 100644 index ce0a7ed16a..0000000000 --- a/en/handbook/chapter.decl +++ /dev/null @@ -1 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> diff --git a/en/handbook/chapters.ent b/en/handbook/chapters.ent deleted file mode 100644 index db8e88a180..0000000000 --- a/en/handbook/chapters.ent +++ /dev/null @@ -1,49 +0,0 @@ -<!-- - Creates entities for each chapter in the FreeBSD Handbook. Each entity - is named chap.foo, where foo is the value of the id attribute on that - chapter, and corresponds to the name of the directory in which that - chapter's .sgml file is stored. - - Chapters should be listed in the order in which they are referenced. - - $Id: chapters.ent,v 1.3 1998-11-12 01:26:17 nik Exp $ ---> - -<!-- Part one --> -<!ENTITY chap.introduction SYSTEM "introduction/chapter.sgml"> -<!ENTITY chap.install SYSTEM "install/chapter.sgml"> -<!ENTITY chap.basics SYSTEM "basics/chapter.sgml"> -<!ENTITY chap.ports SYSTEM "ports/chapter.sgml"> - -<!-- Part two --> -<!ENTITY chap.kernelconfig SYSTEM "kernelconfig/chapter.sgml"> -<!ENTITY chap.security SYSTEM "security/chapter.sgml"> -<!ENTITY chap.printing SYSTEM "printing/chapter.sgml"> -<!ENTITY chap.disks SYSTEM "disks/chapter.sgml"> -<!ENTITY chap.backups SYSTEM "backups/chapter.sgml"> -<!ENTITY chap.quotas SYSTEM "quotas/chapter.sgml"> -<!ENTITY chap.x11 SYSTEM "x11/chapter.sgml"> -<!ENTITY chap.hw SYSTEM "hw/chapter.sgml"> -<!ENTITY chap.l10n SYSTEM "l10n/chapter.sgml"> - -<!-- Part three --> -<!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.sgml"> -<!ENTITY chap.ppp-and-slip SYSTEM "ppp-and-slip/chapter.sgml"> -<!ENTITY chap.advanced-networking SYSTEM "advanced-networking/chapter.sgml"> -<!ENTITY chap.mail SYSTEM "mail/chapter.sgml"> - -<!-- Part four --> -<!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.sgml"> -<!ENTITY chap.contrib SYSTEM "contrib/chapter.sgml"> -<!ENTITY chap.policies SYSTEM "policies/chapter.sgml"> -<!ENTITY chap.kernelopts SYSTEM "kernelopts/chapter.sgml"> -<!ENTITY chap.kerneldebug SYSTEM "kerneldebug/chapter.sgml"> -<!ENTITY chap.linuxemu SYSTEM "linuxemu/chapter.sgml"> -<!ENTITY chap.internals SYSTEM "internals/chapter.sgml"> - -<!-- Part five (appendices) --> -<!ENTITY chap.mirrors SYSTEM "mirrors/chapter.sgml"> -<!ENTITY chap.bibliography SYSTEM "bibliography/chapter.sgml"> -<!ENTITY chap.eresources SYSTEM "eresources/chapter.sgml"> -<!ENTITY chap.staff SYSTEM "staff/chapter.sgml"> -<!ENTITY chap.pgpkeys SYSTEM "pgpkeys/chapter.sgml"> diff --git a/en/handbook/contrib/chapter.sgml b/en/handbook/contrib/chapter.sgml deleted file mode 100644 index b6864ff6ac..0000000000 --- a/en/handbook/contrib/chapter.sgml +++ /dev/null @@ -1,5792 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.90 1999-08-11 13:53:12 alfred Exp $ ---> - -<chapter id="contrib"> - <title>Contributing to FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <para>So you want to contribute something to FreeBSD? That is great! We can - always use the help, and FreeBSD is one of those systems that - <emphasis>relies</emphasis> on the contributions of its user base in order - to survive. Your contributions are not only appreciated, they are vital - to FreeBSD's continued growth!</para> - - <para>Contrary to what some people might also have you believe, you do not - need to be a hot-shot programmer or a close personal friend of the FreeBSD - core team in order to have your contributions accepted. The FreeBSD - Project's development is done by a large and growing number of - international contributors whose ages and areas of technical expertise - vary greatly, and there is always more work to be done than there are - people available to do it.</para> - - <para>Since the FreeBSD project is responsible for an entire operating - system environment (and its installation) rather than just a kernel or a - few scattered utilities, our <filename>TODO</filename> list also spans a - very wide range of tasks, from documentation, beta testing and - presentation to highly specialized types of kernel development. No matter - what your skill level, there is almost certainly something you can do to - help the project!</para> - - <para>Commercial entities engaged in FreeBSD-related enterprises are also - encouraged to contact us. Need a special extension to make your product - work? You will find us receptive to your requests, given that they are not - too outlandish. Working on a value-added product? Please let us know! We - may be able to work cooperatively on some aspect of it. The free software - world is challenging a lot of existing assumptions about how software is - developed, sold, and maintained throughout its life cycle, and we urge you - to at least give it a second look.</para> - - <sect1> - <title>What Is Needed</title> - - <para>The following list of tasks and sub-projects represents something of - an amalgam of the various core team <filename>TODO</filename> lists and - user requests we have collected over the last couple of months. Where - possible, tasks have been ranked by degree of urgency. If you are - interested in working on one of the tasks you see here, send mail to the - coordinator listed by clicking on their names. If no coordinator has - been appointed, maybe you would like to volunteer?</para> - - <sect2> - <title>High priority tasks</title> - - <para>The following tasks are considered to be urgent, usually because - they represent something that is badly broken or sorely needed:</para> - - <orderedlist> - <listitem> - <para>3-stage boot issues. Overall coordination: &a.hackers;</para> - - <itemizedlist> - <listitem> - <para>Do WinNT compatible drive tagging so that the 3rd stage - can provide an accurate mapping of BIOS geometries for - disks.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Filesystem problems. Overall coordination: &a.fs;</para> - - <itemizedlist> - <listitem> - <para>Fix the MSDOS file system.</para> - </listitem> - - <listitem> - <para>Clean up and document the nullfs filesystem code. - Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Fix the union file system. Coordinator: &a.dg;</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Implement Int13 vm86 disk driver. Coordinator: - &a.hackers;</para> - </listitem> - - <listitem> - <para>New bus architecture. Coordinator: &a.newbus;</para> - - <itemizedlist> - <listitem> - <para>Port existing ISA drivers to new architecture.</para> - </listitem> - - <listitem> - <para>Move all interrupt-management code to appropriate parts of - the bus drivers.</para> - </listitem> - - <listitem> - <para>Port PCI subsystem to new architecture. Coordinator: - &a.dfr;</para> - </listitem> - - <listitem> - <para>Figure out the right way to handle removable devices and - then use that as a substrate on which PC-Card and CardBus - support can be implemented.</para> - </listitem> - - <listitem> - <para>Resolve the probe/attach priority issue once and for - all.</para> - </listitem> - - <listitem> - <para>Move any remaining buses over to the new - architecture.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Kernel issues. Overall coordination: &a.hackers;</para> - </listitem> - - <listitem> - <para>Add more pro-active security infrastructure. Overall - coordination: &a.security;</para> - - <itemizedlist> - <listitem> - <para>Build something like Tripwire(TM) into the kernel, with a - remote and local part. There are a number of cryptographic - issues to getting this right; contact the coordinator for - details. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Make the entire kernel use <literal>suser()</literal> - instead of comparing to 0. It is presently using about half - of each. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Split securelevels into different parts, to allow an - administrator to throw away those privileges he can throw - away. Setting the overall securelevel needs to have the same - effect as now, obviously. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Make it possible to upload a list of “allowed - program” to BPF, and then block BPF from accepting other - programs. This would allow BPF to be used e.g. for DHCP, - without allowing an attacker to start snooping the local - network.</para> - </listitem> - - <listitem> - <para>Update the security checker script. We should at least - grab all the checks from the other BSD derivatives, and add - checks that a system with securelevel increased also have - reasonable flags on the relevant parts. Coordinator: - &a.eivind;</para> - </listitem> - - <listitem> - <para>Add authorization infrastructure to the kernel, to allow - different authorization policies. Part of this could be done - by modifying <literal>suser()</literal>. Coordinator: - &a.eivind;</para> - </listitem> - - <listitem> - <para>Add code to the NFS layer so that you cannot - <literal>chdir("..")</literal> out of an NFS partition. E.g., - <filename>/usr</filename> is a UFS partition with - <filename>/usr/src</filename> NFS exported. Now it is - possible to use the NFS filehandle for - <filename>/usr/src</filename> to get access to - <filename>/usr</filename>.</para> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Medium priority tasks</title> - - <para>The following tasks need to be done, but not with any particular - urgency:</para> - - <orderedlist> - <listitem> - <para>Full KLD based driver support/Configuration Manager.</para> - - <itemizedlist> - <listitem> - <para>Write a configuration manager (in the 3rd stage boot?) - that probes your hardware in a sane manner, keeps only the - KLDs required for your hardware, etc.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>PCMCIA/PCCARD. Coordinators: &a.msmith; and &a.phk;</para> - - <itemizedlist> - <listitem> - <para>Documentation!</para> - </listitem> - - <listitem> - <para>Reliable operation of the pcic driver (needs - testing).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>sio.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>ed.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>ep.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>User-mode recognizer and handler (partially done).</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Advanced Power Management. Coordinators: &a.msmith; and - &a.phk;</para> - - <itemizedlist> - <listitem> - <para>APM sub-driver (mostly done).</para> - </listitem> - - <listitem> - <para>IDE/ATA disk sub-driver (partially done).</para> - </listitem> - - <listitem> - <para>syscons/pcvt sub-driver.</para> - </listitem> - - <listitem> - <para>Integration with the PCMCIA/PCCARD drivers - (suspend/resume).</para> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Low priority tasks</title> - - <para>The following tasks are purely cosmetic or represent such an - investment of work that it is not likely that anyone will get them - done anytime soon:</para> - - <para>The first N items are from Terry Lambert - <email>terry@lambert.org</email></para> - - <orderedlist> - <listitem> - <para>NetWare Server (protected mode ODI driver) loader and - subservices to allow the use of ODI card drivers supplied with - network cards. The same thing for NDIS drivers and NetWare SCSI - drivers.</para> - </listitem> - - <listitem> - <para>An "upgrade system" option that works on Linux boxes instead - of just previous rev FreeBSD boxes.</para> - </listitem> - - <listitem> - <para>Symmetric Multiprocessing with kernel preemption (requires - kernel preemption).</para> - </listitem> - - <listitem> - <para>A concerted effort at support for portable computers. This is - somewhat handled by changing PCMCIA bridging rules and power - management event handling. But there are things like detecting - internal vs. external display and picking a different screen - resolution based on that fact, not spinning down the disk if the - machine is in dock, and allowing dock-based cards to disappear - without affecting the machines ability to boot (same issue for - PCMCIA).</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Smaller tasks</title> - - <para>Most of the tasks listed in the previous sections require either a - considerable investment of time or an in-depth knowledge of the - FreeBSD kernel (or both). However, there are also many useful tasks - which are suitable for "weekend hackers", or people without - programming skills.</para> - - <orderedlist> - <listitem> - <para>If you run FreeBSD-current and have a good Internet - connection, there is a machine <hostid - role="fqdn">current.FreeBSD.org</hostid> which builds a full - release once a day — every now and again, try and install - the latest release from it and report any failures in the - process.</para> - </listitem> - - <listitem> - <para>Read the freebsd-bugs mailing list. There might be a - problem you can comment constructively on or with patches you - can test. Or you could even try to fix one of the problems - yourself.</para> - </listitem> - - <listitem> - <para>Read through the FAQ and Handbook periodically. If anything - is badly explained, out of date or even just completely wrong, let - us know. Even better, send us a fix (SGML is not difficult to - learn, but there is no objection to ASCII submissions).</para> - </listitem> - - <listitem> - <para>Help translate FreeBSD documentation into your native language - (if not already available) — just send an email to &a.doc; - asking if anyone is working on it. Note that you are not - committing yourself to translating every single FreeBSD document - by doing this — in fact, the documentation most in need of - translation is the installation instructions.</para> - </listitem> - - <listitem> - <para>Read the freebsd-questions mailing list and &ng.misc - occasionally (or even regularly). It can be very satisfying to - share your expertise and help people solve their problems; - sometimes you may even learn something new yourself! These forums - can also be a source of ideas for things to work on.</para> - </listitem> - - <listitem> - <para>If you know of any bugfixes which have been successfully - applied to -current but have not been merged into -stable after a - decent interval (normally a couple of weeks), send the committer a - polite reminder.</para> - </listitem> - - <listitem> - <para>Move contributed software to <filename>src/contrib</filename> - in the source tree.</para> - </listitem> - - <listitem> - <para>Make sure code in <filename>src/contrib</filename> is up to - date.</para> - </listitem> - - <listitem> - <para>Look for year 2000 bugs (and fix any you find!)</para> - </listitem> - - <listitem> - <para>Build the source tree (or just part of it) with extra warnings - enabled and clean up the warnings.</para> - </listitem> - - <listitem> - <para>Fix warnings for ports which do deprecated things like using - gets() or including malloc.h.</para> - </listitem> - - <listitem> - <para>If you have contributed any ports, send your patches back to - the original author (this will make your life easier when they - bring out the next version)</para> - </listitem> - - <listitem> - <para>Suggest further tasks for this list!</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Work through the PR database</title> - - <para>The <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD PR - list</ulink> shows all the current active problem reports and - requests for enhancement that have been submitted by FreeBSD users. - Look through the open PRs, and see if anything there takes your - interest. Some of these might be very simple tasks, that just need an - extra pair of eyes to look over them and confirm that the fix in the - PR is a good one. Others might be much more complex.</para> - - <para>Start with the PRs that have not been assigned to anyone else, but - if one them is assigned to someone else, but it looks like something - you can handle, e-mail the person it is assigned to and ask if you can - work on it—they might already have a patch ready to be tested, - or further ideas that you can discuss with them.</para> - </sect2> - </sect1> - - <sect1> - <title>How to Contribute</title> - - <para>Contributions to the system generally fall into one or more of the - following 6 categories:</para> - - <sect2 id="contrib-general"> - <title>Bug reports and general commentary</title> - - <para>An idea or suggestion of <emphasis>general</emphasis> technical - interest should be mailed to the &a.hackers;. Likewise, people with - an interest in such things (and a tolerance for a - <emphasis>high</emphasis> volume of mail!) may subscribe to the - hackers mailing list by sending mail to &a.majordomo;. See <link - linkend="eresources-mail">mailing lists</link> for more information - about this and other mailing lists.</para> - - <para>If you find a bug or are submitting a specific change, please - report it using the &man.send-pr.1; program or its <ulink - URL="http://www.FreeBSD.org/send-pr.html">WEB-based - equivalent</ulink>. Try to fill-in each field of the bug report. - Unless they exceed 65KB, include any patches directly in the report. - When including patches, <emphasis>do not</emphasis> use cut-and-paste - because cut-and-paste turns tabs into spaces and makes them unusable. - Consider compressing patches and using &man.uuencode.1; if they exceed - 20KB. Upload very large submissions to <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming/">ftp.FreeBSD.org:/pub/FreeBSD/incoming/</ulink>.</para> - - <para>After filing a report, you should receive confirmation along with - a tracking number. Keep this tracking number so that you can update - us with details about the problem by sending mail to - <email>bug-followup@FreeBSD.org</email>. Use the number as the - message subject, e.g. <literal>"Re: kern/3377"</literal>. Additional - information for any bug report should be submitted this way.</para> - - <para>If you do not receive confirmation in a timely fashion (3 days to - a week, depending on your email connection) or are, for some reason, - unable to use the &man.send-pr.1; command, then you may ask - someone to file it for you by sending mail to the &a.bugs;.</para> - </sect2> - - <sect2> - <title>Changes to the documentation</title> - - <para>Changes to the documentation are overseen by the &a.doc;. Send - submissions and changes (even small ones are welcome!) using - <command>send-pr</command> as described in <link - linkend="contrib-general">Bug Reports and General - Commentary</link>.</para> - </sect2> - - <sect2> - <title>Changes to existing source code</title> - - <para>An addition or change to the existing source code is a somewhat - trickier affair and depends a lot on how far out of date you are with - the current state of the core FreeBSD development. There is a special - on-going release of FreeBSD known as “FreeBSD-current” - which is made available in a variety of ways for the convenience of - developers working actively on the system. See <link - linkend="current">Staying current with FreeBSD</link> for more - information about getting and using FreeBSD-current.</para> - - <para>Working from older sources unfortunately means that your changes - may sometimes be too obsolete or too divergent for easy re-integration - into FreeBSD. Chances of this can be minimized somewhat by - subscribing to the &a.announce; and the &a.current; lists, where - discussions on the current state of the system take place.</para> - - <para>Assuming that you can manage to secure fairly up-to-date sources - to base your changes on, the next step is to produce a set of diffs to - send to the FreeBSD maintainers. This is done with the &man.diff.1; - command, with the “context diff” form - being preferred. For example:</para> - - <para> - <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen> - - or - - <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen> - - would generate such a set of context diffs for the given source file - or directory hierarchy. See the man page for &man.diff.1; for more - details.</para> - - <para>Once you have a set of diffs (which you may test with the - &man.patch.1; command), you should submit them for inclusion with - FreeBSD. Use the &man.send-pr.1; program as described in <link - linkend="contrib-general">Bug Reports and General Commentary</link>. - <emphasis>Do not</emphasis> just send the diffs to the &a.hackers; or - they will get lost! We greatly appreciate your submission (this is a - volunteer project!); because we are busy, we may not be able to - address it immediately, but it will remain in the pr database until we - do.</para> - - <para>If you feel it appropriate (e.g. you have added, deleted, or - renamed files), bundle your changes into a <command>tar</command> file - and run the &man.uuencode.1; program on it. Shar archives are also - welcome.</para> - - <para>If your change is of a potentially sensitive nature, e.g. you are - unsure of copyright issues governing its further distribution or you - are simply not ready to release it without a tighter review first, - then you should send it to &a.core; directly rather than submitting it - with &man.send-pr.1;. The core mailing list reaches a much smaller - group of people who do much of the day-to-day work on FreeBSD. Note - that this group is also <emphasis>very busy</emphasis> and so you - should only send mail to them where it is truly necessary.</para> - - <para>Please refer to <command>man 9 intro</command> and <command>man 9 - style</command> for some information on coding style. We would - appreciate it if you were at least aware of this information before - submitting code.</para> - </sect2> - - <sect2> - <title>New code or major value-added packages</title> - - <para>In the rare case of a significant contribution of a large body - work, or the addition of an important new feature to FreeBSD, it - becomes almost always necessary to either send changes as uuencode'd - tar files or upload them to our ftp site <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming">ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming</ulink>.</para> - - <para>When working with large amounts of code, the touchy subject of - copyrights also invariably comes up. Acceptable copyrights for code - included in FreeBSD are:</para> - - <orderedlist> - <listitem> - <para>The BSD copyright. This copyright is most preferred due to - its “no strings attached” nature and general - attractiveness to commercial enterprises. Far from discouraging - such commercial use, the FreeBSD Project actively encourages such - participation by commercial interests who might eventually be - inclined to invest something of their own into FreeBSD.</para> - </listitem> - - <listitem> - <para>The GNU Public License, or “GPL”. This license is - not quite as popular with us due to the amount of extra effort - demanded of anyone using the code for commercial purposes, but - given the sheer quantity of GPL'd code we currently require - (compiler, assembler, text formatter, etc) it would be silly to - refuse additional contributions under this license. Code under - the GPL also goes into a different part of the tree, that being - <filename>/sys/gnu</filename> or - <filename>/usr/src/gnu</filename>, and is therefore easily - identifiable to anyone for whom the GPL presents a problem.</para> - </listitem> - </orderedlist> - - <para>Contributions coming under any other type of copyright must be - carefully reviewed before their inclusion into FreeBSD will be - considered. Contributions for which particularly restrictive - commercial copyrights apply are generally rejected, though the authors - are always encouraged to make such changes available through their own - channels.</para> - - <para>To place a “BSD-style” copyright on your work, include - the following text at the very beginning of every source code file you - wish to protect, replacing the text between the <literal>%%</literal> - with the appropriate information.</para> - - <programlisting> -Copyright (c) %%proper_years_here%% - %%your_name_here%%, %%your_state%% %%your_zip%%. - All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer as - the first lines of this file unmodified. -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF -THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - $Id$</programlisting> - - <para>For your convenience, a copy of this text can be found in - <filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para> - </sect2> - - <sect2> - <title>Money, Hardware or Internet access</title> - - <para>We are always very happy to accept donations to further the cause - of the FreeBSD Project and, in a volunteer effort like ours, a little - can go a long way! Donations of hardware are also very important to - expanding our list of supported peripherals since we generally lack - the funds to buy such items ourselves.</para> - - <sect3> - <title><anchor id="donations">Donating funds</title> - - <para>While the FreeBSD Project is not a 501(c)(3) (charitable) - corporation and hence cannot offer special tax incentives for any - donations made, any such donations will be gratefully accepted on - behalf of the project by FreeBSD, Inc.</para> - - <para>FreeBSD, Inc. was founded in early 1995 by &a.jkh; and &a.dg; - with the goal of furthering the aims of the FreeBSD Project and - giving it a minimal corporate presence. Any and all funds donated - (as well as any profits that may eventually be realized by FreeBSD, - Inc.) will be used exclusively to further the project's - goals.</para> - - <para>Please make any checks payable to FreeBSD, Inc., sent in care of - the following address:</para> - - <address> - <otheraddr>FreeBSD, Inc.</otheraddr> - <otheraddr>c/o Jordan Hubbard</otheraddr> - <street>4041 Pike Lane, Suite F</street> - <city>Concord</city> - <state>CA</state>, <postcode>94520</postcode> - </address> - - <para>(currently using the Walnut Creek CDROM address until a PO box - can be opened)</para> - - <para>Wire transfers may also be sent directly to:</para> - - <address> - <otheraddr>Bank Of America</otheraddr> - <otheraddr>Concord Main Office</otheraddr> - <pob>P.O. Box 37176</pob> - <city>San Francisco</city> - <state>CA</state>, <postcode>94137-5176</postcode> - - <otheraddr>Routing #: 121-000-358</otheraddr> - <otheraddr>Account #: 01411-07441 (FreeBSD, Inc.)</otheraddr> - </address> - - <para>Any correspondence related to donations should be sent to &a.jkh, - either via email or to the FreeBSD, Inc. postal address given above. - </para> - - <para>If you do not wish to be listed in our <link - linkend="donors">donors</link> section, please specify this when - making your donation. Thanks!</para> - </sect3> - - <sect3> - <title>Donating hardware</title> - - <para>Donations of hardware in any of the 3 following categories are - also gladly accepted by the FreeBSD Project:</para> - - <itemizedlist> - <listitem> - <para>General purpose hardware such as disk drives, memory or - complete systems should be sent to the FreeBSD, Inc. address - listed in the <emphasis>donating funds</emphasis> - section.</para> - </listitem> - - <listitem> - <para>Hardware for which ongoing compliance testing is desired. - We are currently trying to put together a testing lab of all - components that FreeBSD supports so that proper regression - testing can be done with each new release. We are still lacking - many important pieces (network cards, motherboards, etc) and if - you would like to make such a donation, please contact &a.dg; - for information on which items are still required.</para> - </listitem> - - <listitem> - <para>Hardware currently unsupported by FreeBSD for which you - would like to see such support added. Please contact the - &a.core; before sending such items as we will need to find a - developer willing to take on the task before we can accept - delivery of new hardware.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Donating Internet access</title> - - <para>We can always use new mirror sites for FTP, WWW or - <command>cvsup</command>. If you would like to be such a mirror, - please contact the FreeBSD project administrators - <email>admin@FreeBSD.org</email> for more information.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="donors"> - <title>Donors Gallery</title> - - <para>The FreeBSD Project is indebted to the following donors and would - like to publically thank them here!</para> - - <itemizedlist> - <listitem> - <para><emphasis>Contributors to the central server - project:</emphasis></para> - - <para>The following individuals and businesses made it possible for - the FreeBSD Project to build a new central server machine to - eventually replace <hostid role="fqdn">freefall.FreeBSD.org</hostid> - by donating the following items:</para> - - <itemizedlist> - <listitem> - <para>&a.mbarkah and his employer, <ulink URL="http://www.hemi.com"> - Hemisphere Online</ulink>, donated a <emphasis>Pentium Pro - (P6) 200Mhz CPU</emphasis></para> - </listitem> - - <listitem> - <para><ulink URL="http://www.asacomputers.com">ASA - Computers</ulink> donated a <emphasis>Tyan 1662 - motherboard</emphasis>.</para> - </listitem> - - <listitem> - <para>Joe McGuckin <email>joe@via.net</email> of <ulink - URL="http://www.via.net">ViaNet Communications</ulink> donated - a <emphasis>Kingston ethernet controller.</emphasis></para> - </listitem> - - <listitem> - <para>Jack O'Neill <email>jack@diamond.xtalwind.net</email> - donated an <emphasis>NCR 53C875 SCSI controller - card</emphasis>.</para> - </listitem> - - <listitem> - <para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <ulink - URL="http://www.Alameda.net">Alameda Networks</ulink> donated - <emphasis>128MB of memory</emphasis>, a <emphasis>4 Gb disk - drive and the case.</emphasis></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Direct funding:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed direct funding to the project:</para> - - <itemizedlist> - <listitem> - <para>Annelise Anderson - <email>ANDRSN@HOOVER.STANFORD.EDU</email></para> - </listitem> - - <listitem> - <para>&a.dillon</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.epilogue.com/">Epilogue Technology - Corporation</ulink></para> - </listitem> - - <listitem> - <para>&a.sef</para> - </listitem> - - <listitem> - <para>Don Scott Wilde</para> - </listitem> - - <listitem> - <para>Gianmarco Giovannelli - <email>gmarco@masternet.it</email></para> - </listitem> - - <listitem> - <para>Josef C. Grosch <email>joeg@truenorth.org</email></para> - </listitem> - - <listitem> - <para>Robert T. Morris</para> - </listitem> - - <listitem> - <para>&a.chuckr</para> - </listitem> - - <listitem> - <para>Kenneth P. Stox <email>ken@stox.sa.enteract.com</email> of - <ulink URL="http://www.imagescape.com">Imaginary Landscape, - LLC.</ulink></para> - </listitem> - - <listitem> - <para>Dmitry S. Kohmanyuk <email>dk@dog.farm.org</email></para> - </listitem> - - <listitem> - <para><ulink URL="http://www.cdrom.co.jp/">Laser5</ulink> of Japan - (a portion of the profits from sales of their various FreeBSD - CD-ROMs.</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.mmjp.or.jp/fuki/">Fuki Shuppan - Publishing Co.</ulink> donated a portion of their profits from - <emphasis>Hajimete no FreeBSD</emphasis> (FreeBSD, Getting - started) to the FreeBSD and XFree86 projects.</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.ascii.co.jp/">ASCII Corp.</ulink> - donated a portion of their profits from several FreeBSD-related - books to the FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.yokogawa.co.jp/">Yokogawa Electric - Corp</ulink> has generously donated significant funding to the - FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.buffnet.net/">BuffNET</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.pacificsolutions.com/">Pacific - Solutions</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.siemens.de/">Siemens AG</ulink> - via <ulink url="mailto:andre.albsmeier@mchp.siemens.de">Andre - Albsmeier</ulink></para> - </listitem> - - <listitem> - <para><ulink url="mailto:ras@interaccess.com">Chris Silva</ulink> - </para> - </listitem> - - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Hardware contributors:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed hardware for testing and device driver - development/support:</para> - - <itemizedlist> - <listitem> - <para>Walnut Creek CDROM for providing the Pentium P5-90 and - 486/DX2-66 EISA/VL systems that are being used for our - development work, to say nothing of the network access and other - donations of hardware resources.</para> - </listitem> - - <listitem> - <para>TRW Financial Systems, Inc. provided 130 PCs, three 68 GB - fileservers, twelve Ethernets, two routers and an ATM switch for - debugging the diskless code.</para> - </listitem> - - <listitem> - <para>Dermot McDonnell donated the Toshiba XM3401B CDROM drive - currently used in freefall.</para> - </listitem> - - <listitem> - <para>&a.chuck; contributed his floppy tape streamer for - experimental work.</para> - </listitem> - - <listitem> - <para>Larry Altneu <email>larry@ALR.COM</email>, and &a.wilko;, - provided Wangtek and Archive QIC-02 tape drives in order to - improve the <devicename>wt</devicename> driver.</para> - </listitem> - - <listitem> - <para>Ernst Winter <email>ewinter@lobo.muc.de</email> contributed - a 2.88 MB floppy drive to the project. This will hopefully - increase the pressure for rewriting the floppy disk driver. - <!-- smiley -->;-)</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.tekram.com">Tekram - Technologies</ulink> sent one each of their DC-390, DC-390U - and DC-390F FAST and ULTRA SCSI host adapter cards for - regression testing of the NCR and AMD drivers with their cards. - They are also to be applauded for making driver sources for free - operating systems available from their FTP server <ulink - URL="ftp://ftp.tekram.com/scsi/FreeBSD">ftp://ftp.tekram.com/scsi/FreeBSD</ulink>.</para> - </listitem> - - <listitem> - <para><email>Larry M. Augustin</email> contributed not only a - Symbios Sym8751S SCSI card, but also a set of data books, - including one about the forthcoming Sym53c895 chip with Ultra-2 - and LVD support, and the latest programming manual with - information on how to safely use the advanced features of the - latest Symbios SCSI chips. Thanks a lot!</para> - </listitem> - - <listitem> - <para>Christoph Kukulies <email>kuku@FreeBSD.org</email> donated - an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver - development.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Special contributors:</emphasis></para> - - <itemizedlist> - <listitem> - <para><ulink URL="http://www.cdrom.com">Walnut Creek CDROM</ulink> - has donated almost more than we can say (see the <link - linkend="history">history</link> document for more details). - In particular, we would like to thank them for the original - hardware used for <hostid - role="fqdn">freefall.FreeBSD.org</hostid>, our primary - development machine, and for <hostid - role="fqdn">thud.FreeBSD.org</hostid>, a testing and build - box. We are also indebted to them for funding various - contributors over the years and providing us with unrestricted - use of their T1 connection to the Internet.</para> - </listitem> - - <listitem> - <para>The <ulink URL="http://www.interface-business.de">interface - business GmbH, Dresden</ulink> has been patiently supporting - &a.joerg; who has often preferred FreeBSD work over paywork, and - used to fall back to their (quite expensive) EUnet Internet - connection whenever his private connection became too slow or - flakey to work with it...</para> - </listitem> - - <listitem> - <para><ulink URL="http://www.bsdi.com">Berkeley Software Design, - Inc.</ulink> has contributed their DOS emulator code to the - remaining BSD world, which is used in the - <emphasis>doscmd</emphasis> command.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Core Team Alumni</title> - - <para>The following people were members of the FreeBSD core team during - the periods indicated. We thank them for their past efforts in the - service of the FreeBSD project.</para> - - <para><emphasis>In rough chronological order:</emphasis></para> - - <itemizedlist> - <listitem> - <para>&a.guido (1995 - 1999)</para> - </listitem> - - <listitem> - <para>&a.dyson (1993 - 1998)</para> - </listitem> - - <listitem> - <para>&a.nate (1992 - 1996)</para> - </listitem> - - <listitem> - <para>&a.rgrimes (1992 - 1995)</para> - </listitem> - - <listitem> - <para>Andreas Schulz (1992 - 1995)</para> - </listitem> - - <listitem> - <para>&a.csgr (1993 - 1995)</para> - </listitem> - - <listitem> - <para>&a.paul (1992 - 1995)</para> - </listitem> - - <listitem> - <para>&a.smace (1993 - 1994)</para> - </listitem> - - <listitem> - <para>Andrew Moore (1993 - 1994)</para> - </listitem> - - <listitem> - <para>Christoph Robitschko (1993 - 1994)</para> - </listitem> - - <listitem> - <para>J. T. Conklin (1992 - 1993)</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Derived Software Contributors</title> - - <para>This software was originally derived from William F. Jolitz's 386BSD - release 0.1, though almost none of the original 386BSD specific code - remains. This software has been essentially re-implemented from the - 4.4BSD-Lite release provided by the Computer Science Research Group - (CSRG) at the University of California, Berkeley and associated academic - contributors.</para> - - <para>There are also portions of NetBSD and OpenBSD that have been - integrated into FreeBSD as well, and we would therefore like to thank - all the contributors to NetBSD and OpenBSD for their work.</para> - </sect1> - - <sect1 id="contrib-additional"> - <title>Additional FreeBSD Contributors</title> - - <para>(in alphabetical order by first name):</para> - - <itemizedlist> - <listitem> - <para>ABURAYA Ryushirou <email>rewsirow@ff.iij4u.or.jp</email></para> - </listitem> - - <listitem> - <para>AMAGAI Yoshiji <email>amagai@nue.org</email></para> - </listitem> - - <listitem> - <para>Aaron Bornstein <email>aaronb@j51.com</email></para> - </listitem> - - <listitem> - <para>Aaron Smith <email>aaron@mutex.org</email></para> - </listitem> - - <listitem> - <para>Achim Patzner <email>ap@noses.com</email></para> - </listitem> - - <listitem> - <para>Ada T Lim <email>ada@bsd.org</email></para> - </listitem> - - <listitem> - <para>Adam Baran <email>badam@mw.mil.pl</email></para> - </listitem> - - <listitem> - <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adam McDougall <email>mcdouga9@egr.msu.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Colley <email>aecolley@ois.ie</email></para> - </listitem> - - <listitem> - <para>Adrian Hall <email>adrian@ibmpcug.co.uk</email></para> - </listitem> - - <listitem> - <para>Adrian Mariano <email>adrian@cam.cornell.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Steinmann <email>ast@marabu.ch</email></para> - </listitem> - - <listitem> - <para>Adam Strohl <email>troll@digitalspark.net</email></para> - </listitem> - - <listitem> - <para>Adrian T. Filipi-Martin - <email>atf3r@agate.cs.virginia.edu</email></para> - </listitem> - - <listitem> - <para>Ajit Thyagarajan <email>unknown</email></para> - </listitem> - - <listitem> - <para>Akio Morita - <email>amorita@meadow.scphys.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Akira SAWADA <email>unknown</email></para> - </listitem> - - <listitem> - <para>Akira Watanabe - <email>akira@myaw.ei.meisei-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Akito Fujita <email>fujita@zoo.ncl.omron.co.jp</email></para> - </listitem> - - <listitem> - <para>Alain Kalker - <email>A.C.P.M.Kalker@student.utwente.nl</email></para> - </listitem> - - <listitem> - <para>Alan Bawden <email>alan@curry.epilogue.com</email></para> - </listitem> - - <listitem> - <para>Alec Wolman <email>wolman@cs.washington.edu</email></para> - </listitem> - - <listitem> - <para>Aled Morris <email>aledm@routers.co.uk</email></para> - </listitem> - - <listitem> - <para>Alex <email>garbanzo@hooked.net</email></para> - </listitem> - - <listitem> - <para>Alex D. Chen - <email>dhchen@Canvas.dorm7.nccu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Alex G. Bulushev <email>bag@demos.su</email></para> - </listitem> - - <listitem> - <para>Alex Le Heux <email>alexlh@funk.org</email></para> - </listitem> - - <listitem> - <para>Alex Perel <email>veers@disturbed.net</email></para> - </listitem> - - <listitem> - <para>Alexander B. Povolotsky <email>tarkhil@mgt.msk.ru</email></para> - </listitem> - - <listitem> - <para>Alexander Leidinger - <email>netchild@wurzelausix.CS.Uni-SB.DE</email></para> - </listitem> - - <listitem> - <para>Alexander Langer <email>alex@cichlids.com</email></para> - </listitem> - - <listitem> - <para>Alexandre Snarskii <email>snar@paranoia.ru</email></para> - </listitem> - - <listitem> - <para>Alistair G. Crooks <email>agc@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Allan Saddi <email>asaddi@philosophysw.com</email></para> - </listitem> - - <listitem> - <para>Allen Campbell <email>allenc@verinet.com</email></para> - </listitem> - - <listitem> - <para>Amakawa Shuhei <email>amakawa@hoh.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Amancio Hasty <email>hasty@star-gate.com</email></para> - </listitem> - - <listitem> - <para>Amir Farah <email>amir@comtrol.com</email></para> - </listitem> - - <listitem> - <para>Amy Baron <email>amee@beer.org</email></para> - </listitem> - - <listitem> - <para>Anatoly A. Orehovsky <email>tolik@mpeks.tomsk.su</email></para> - </listitem> - - <listitem> - <para>Anatoly Vorobey <email>mellon@pobox.com</email></para> - </listitem> - - <listitem> - <para>Anders Nordby <email>nickerne@nome.no</email></para> - </listitem> - - <listitem> - <para>Anders Thulin <email>Anders.X.Thulin@telia.se</email></para> - </listitem> - - <listitem> - <para>Andras Olah <email>olah@cs.utwente.nl</email></para> - </listitem> - - <listitem> - <para>Andre Albsmeier - <email>Andre.Albsmeier@mchp.siemens.de</email></para> - </listitem> - - <listitem> - <para>Andre Oppermann <email>andre@pipeline.ch</email></para> - </listitem> - - <listitem> - <para>Andreas Haakh <email>ah@alman.robin.de</email></para> - </listitem> - - <listitem> - <para>Andreas Kohout <email>shanee@rabbit.augusta.de</email></para> - </listitem> - - <listitem> - <para>Andreas Lohr <email>andreas@marvin.RoBIN.de</email></para> - </listitem> - - <listitem> - <para>Andreas Schulz <email>unknown</email></para> - </listitem> - - <listitem> - <para>Andreas Wetzel <email>mickey@deadline.snafu.de</email></para> - </listitem> - - <listitem> - <para>Andreas Wrede <email>andreas@planix.com</email></para> - </listitem> - - <listitem> - <para>Andres Vega Garcia <email>unknown</email></para> - </listitem> - - <listitem> - <para>Andrew Atrens <email>atreand@statcan.ca</email></para> - </listitem> - - <listitem> - <para>Andrew Boothman <email>andrew@cream.org</email></para> - </listitem> - - <listitem> - <para>Andrew Gillham <email>gillham@andrews.edu</email></para> - </listitem> - - <listitem> - <para>Andrew Gordon <email>andrew.gordon@net-tel.co.uk</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew J. Korty <email>ajk@purdue.edu</email></para> - </listitem> - - <listitem> - <para>Andrew L. Moore <email>alm@mclink.com</email></para> - </listitem> - - <listitem> - <para>Andrew McRae <email>amcrae@cisco.com</email></para> - </listitem> - - <listitem> - <para>Andrew Stevenson <email>andrew@ugh.net.au</email></para> - </listitem> - - <listitem> - <para>Andrew Timonin <email>tim@pool1.convey.ru</email></para> - </listitem> - - <listitem> - <para>Andrew V. Stesin <email>stesin@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Andrew Webster <email>awebster@dataradio.com</email></para> - </listitem> - - <listitem> - <para>Andrey Zakhvatov <email>andy@icc.surw.chel.su</email></para> - </listitem> - - <listitem> - <para>Andy Farkas <email>andyf@speednet.com.au</email></para> - </listitem> - - <listitem> - <para>Andy Valencia <email>ajv@csd.mot.com</email></para> - </listitem> - - <listitem> - <para>Andy Whitcroft <email>andy@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Angelo Turetta <email>ATuretta@stylo.it</email></para> - </listitem> - - <listitem> - <para>Anthony C. Chavez <email>magus@xmission.com</email></para> - </listitem> - - <listitem> - <para>Anthony Yee-Hang Chan <email>yeehang@netcom.com</email></para> - </listitem> - - <listitem> - <para>Anton Berezin <email>tobez@plab.ku.dk</email></para> - </listitem> - - <listitem> - <para>Antti Kaipila <email>anttik@iki.fi</email></para> - </listitem> - - <listitem> - <para>Are Bryne <email>are.bryne@communique.no</email></para> - </listitem> - - <listitem> - <para>Ari Suutari <email>ari@suutari.iki.fi</email></para> - </listitem> - - <listitem> - <para>Arjan de Vet <email>devet@IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Assar Westerlund <email>assar@sics.se</email></para> - </listitem> - - <listitem> - <para>Atsushi Furuta <email>furuta@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Atsushi Murai <email>amurai@spec.co.jp</email></para> - </listitem> - - <listitem> - <para>Bakul Shah <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Bierbauch <email>pivrnec@vszbr.cz</email></para> - </listitem> - - <listitem> - <para>Barry Lustig <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Ben Hutchinson <email>benhutch@xfiles.org.uk</email></para> - </listitem> - - <listitem> - <para>Ben Jackson <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ben Smithurst <email>ben@scientia.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Ben Walter <email>bwalter@itachi.swcp.com</email></para> - </listitem> - - <listitem> - <para>Benjamin Lewis <email>bhlewis@gte.net</email></para> - </listitem> - - <listitem> - <para>Bernd Rosauer <email>br@schiele-ct.de</email></para> - </listitem> - - <listitem> - <para>Bill Kish <email>kish@osf.org</email></para> - </listitem> - - <listitem> - <para>Bill Trost <email>trost@cloud.rain.com</email></para> - </listitem> - - <listitem> - <para>Blaz Zupan <email>blaz@amis.net</email></para> - </listitem> - - <listitem> - <para>Bob Van Valzah <email>Bob@whitebarn.com</email></para> - </listitem> - - <listitem> - <para>Bob Willcox <email>bob@luke.pmr.com</email></para> - </listitem> - - <listitem> - <para>Boris Staeblow <email>balu@dva.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Boyd R. Faulkner <email>faulkner@asgard.bga.com</email></para> - </listitem> - - <listitem> - <para>Brad Karp <email>karp@eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>Bradley Dunn <email>bradley@dunn.org</email></para> - </listitem> - - <listitem> - <para>Brandon Fosdick <email>bfoz@glue.umd.edu</email></para> - </listitem> - - <listitem> - <para>Brandon Gillespie <email>brandon@roguetrader.com</email></para> - </listitem> - - <listitem> - <para>&a.wlloyd</para> - </listitem> - - <listitem> - <para>Bob Wilcox <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Boyd Faulkner <email>faulkner@mpd.tandem.com</email></para> - </listitem> - - <listitem> - <para>Brent J. Nordquist <email>bjn@visi.com</email></para> - </listitem> - - <listitem> - <para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Brett Taylor - <email>brett@peloton.physics.montana.edu</email></para> - </listitem> - - <listitem> - <para>Brian Campbell <email>brianc@pobox.com</email></para> - </listitem> - - <listitem> - <para>Brian Clapper <email>bmc@willscreek.com</email></para> - </listitem> - - <listitem> - <para>Brian Cully <email>shmit@kublai.com</email></para> - </listitem> - - <listitem> - <para>Brian Handy - <email>handy@lambic.space.lockheed.com</email></para> - </listitem> - - <listitem> - <para>Brian Litzinger <email>brian@MediaCity.com</email></para> - </listitem> - - <listitem> - <para>Brian McGovern <email>bmcgover@cisco.com</email></para> - </listitem> - - <listitem> - <para>Brian Moore <email>ziff@houdini.eecs.umich.edu</email></para> - </listitem> - - <listitem> - <para>Brian R. Haug <email>haug@conterra.com</email></para> - </listitem> - - <listitem> - <para>Brian Tao <email>taob@risc.org</email></para> - </listitem> - - <listitem> - <para>Brion Moss <email>brion@queeg.com</email></para> - </listitem> - - <listitem> - <para>Bruce A. Mah <email>bmah@ca.sandia.gov</email></para> - </listitem> - - <listitem> - <para>Bruce Albrecht <email>bruce@zuhause.mn.org</email></para> - </listitem> - - <listitem> - <para>Bruce Gingery <email>bgingery@gtcs.com</email></para> - </listitem> - - <listitem> - <para>Bruce J. Keeler <email>loodvrij@gridpoint.com</email></para> - </listitem> - - <listitem> - <para>Bruce Murphy <email>packrat@iinet.net.au</email></para> - </listitem> - - <listitem> - <para>Bruce Walter <email>walter@fortean.com</email></para> - </listitem> - - <listitem> - <para>Carey Jones <email>mcj@acquiesce.org</email></para> - </listitem> - - <listitem> - <para>Carl Fongheiser <email>cmf@netins.net</email></para> - </listitem> - - <listitem> - <para>Carl Mascott <email>cmascott@world.std.com</email></para> - </listitem> - - <listitem> - <para>Casper <email>casper@acc.am</email></para> - </listitem> - - <listitem> - <para>Castor Fu <email>castor@geocast.com</email></para> - </listitem> - - <listitem> - <para>Cejka Rudolf <email>cejkar@dcse.fee.vutbr.cz</email></para> - </listitem> - - <listitem> - <para>Chain Lee <email>chain@110.net</email></para> - </listitem> - - <listitem> - <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Charles Henrich <email>henrich@msu.edu</email></para> - </listitem> - - <listitem> - <para>Charles Mott <email>cmott@srv.net</email></para> - </listitem> - - <listitem> - <para>Charles Owens <email>owensc@enc.edu</email></para> - </listitem> - - <listitem> - <para>Chet Ramey <email>chet@odin.INS.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Chia-liang Kao <email>clkao@CirX.ORG</email></para> - </listitem> - - <listitem> - <para>Chiharu Shibata <email>chi@bd.mbn.or.jp</email></para> - </listitem> - - <listitem> - <para>Chip Norkus <email>unknown</email></para> - </listitem> - - <listitem> - <para>Choi Jun Ho <email>junker@jazz.snu.ac.kr</email></para> - </listitem> - - <listitem> - <para>Chris Csanady <email>cc@tarsier.ca.sandia.gov</email></para> - </listitem> - - <listitem> - <para>Chris Dabrowski <email>chris@vader.org</email></para> - </listitem> - - <listitem> - <para>Chris Dillon <email>cdillon@wolves.k12.mo.us</email></para> - </listitem> - - <listitem> - <para>Chris Shenton - <email>cshenton@angst.it.hq.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Chris Stenton <email>jacs@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>Chris Timmons <email>skynyrd@opus.cts.cwu.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christian Gusenbauer - <email>cg@fimp01.fim.uni-linz.ac.at</email></para> - </listitem> - - <listitem> - <para>Christian Haury <email>Christian.Haury@sagem.fr</email></para> - </listitem> - - <listitem> - <para>Christian Weisgerber - <email>naddy@bigeye.rhein-neckar.de</email></para> - </listitem> - - <listitem> - <para>Christoph P. Kukulies <email>kuku@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko - <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Christoph Weber-Fahr - <email>wefa@callcenter.systemhaus.net</email></para> - </listitem> - - <listitem> - <para>Christopher G. Demetriou - <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Christopher T. Johnson - <email>cjohnson@neunacht.netgsi.com</email></para> - </listitem> - - <listitem> - <para>Chrisy Luke <email>chrisy@flix.net</email></para> - </listitem> - - <listitem> - <para>Chuck Hein <email>chein@cisco.com</email></para> - </listitem> - - <listitem> - <para>Clive Lin <email>clive@CiRX.ORG</email></para> - </listitem> - - <listitem> - <para>Colman Reilly <email>careilly@tcd.ie</email></para> - </listitem> - - <listitem> - <para>Conrad Sabatier <email>conrads@neosoft.com</email></para> - </listitem> - - <listitem> - <para>Coranth Gryphon <email>gryphon@healer.com</email></para> - </listitem> - - <listitem> - <para>Cornelis van der Laan - <email>nils@guru.ims.uni-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Cove Schneider <email>cove@brazil.nbn.com</email></para> - </listitem> - - <listitem> - <para>Craig Leres <email>leres@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Craig Loomis <email>unknown</email></para> - </listitem> - - <listitem> - <para>Craig Metz <email>cmetz@inner.net</email></para> - </listitem> - - <listitem> - <para>Craig Spannring <email>cts@internetcds.com</email></para> - </listitem> - - <listitem> - <para>Craig Struble <email>cstruble@vt.edu</email></para> - </listitem> - - <listitem> - <para>Cristian Ferretti <email>cfs@riemann.mat.puc.cl</email></para> - </listitem> - - <listitem> - <para>Curt Mayer <email>curt@toad.com</email></para> - </listitem> - - <listitem> - <para>Cy Schubert <email>cschuber@uumail.gov.bc.ca</email></para> - </listitem> - - <listitem> - <para>DI. Christian Gusenbauer - <email>cg@scotty.edvz.uni-linz.ac.at</email></para> - </listitem> - - <listitem> - <para>Dai Ishijima <email>ishijima@tri.pref.osaka.jp</email></para> - </listitem> - - <listitem> - <para>Damian Hamill <email>damian@cablenet.net</email></para> - </listitem> - - <listitem> - <para>Dan Cross <email>tenser@spitfire.ecsel.psu.edu</email></para> - </listitem> - - <listitem> - <para>Dan Lukes <email>dan@obluda.cz</email></para> - </listitem> - - <listitem> - <para>Dan Nelson <email>dnelson@emsphone.com</email></para> - </listitem> - - <listitem> - <para>Dan Walters <email>hannibal@cyberstation.net</email></para> - </listitem> - - <listitem> - <para>Daniel M. Eischen - <email>deischen@iworks.InterWorks.org</email></para> - </listitem> - - <listitem> - <para>Daniel O'Connor <email>doconnor@gsoft.com.au</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Daniel Rock <email>rock@cs.uni-sb.de</email></para> - </listitem> - - <listitem> - <para>Danny Egen <email>unknown</email></para> - </listitem> - - <listitem> - <para>Danny J. Zerkel <email>dzerkel@phofarm.com</email></para> - </listitem> - - <listitem> - <para>Darren Reed <email>avalon@coombs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Dave Adkins <email>adkin003@tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>Dave Andersen <email>angio@aros.net</email></para> - </listitem> - - <listitem> - <para>Dave Blizzard <email>dblizzar@sprynet.com</email></para> - </listitem> - - <listitem> - <para>Dave Bodenstab <email>imdave@synet.net</email></para> - </listitem> - - <listitem> - <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Chapeskie <email>dchapes@ddm.on.ca</email></para> - </listitem> - - <listitem> - <para>Dave Cornejo <email>dave@dogwood.com</email></para> - </listitem> - - <listitem> - <para>Dave Edmondson <email>davided@sco.com</email></para> - </listitem> - - <listitem> - <para>Dave Glowacki <email>dglo@ssec.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Dave Marquardt <email>marquard@austin.ibm.com</email></para> - </listitem> - - <listitem> - <para>Dave Tweten <email>tweten@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>David A. Adkins <email>adkin003@tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>David A. Bader <email>dbader@umiacs.umd.edu</email></para> - </listitem> - - <listitem> - <para>David Borman <email>dab@bsdi.com</email></para> - </listitem> - - <listitem> - <para>David Dawes <email>dawes@XFree86.org</email></para> - </listitem> - - <listitem> - <para>David Filo <email>filo@yahoo.com</email></para> - </listitem> - - <listitem> - <para>David Holland <email>dholland@eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>David Holloway <email>daveh@gwythaint.tamis.com</email></para> - </listitem> - - <listitem> - <para>David Horwitt <email>dhorwitt@ucsd.edu</email></para> - </listitem> - - <listitem> - <para>David Hovemeyer <email>daveho@infocom.com</email></para> - </listitem> - - <listitem> - <para>David Jones <email>dej@qpoint.torfree.net</email></para> - </listitem> - - <listitem> - <para>David Kelly <email>dkelly@tomcat1.tbe.com</email></para> - </listitem> - - <listitem> - <para>David Kulp <email>dkulp@neomorphic.com</email></para> - </listitem> - - <listitem> - <para>David L. Nugent <email>davidn@blaze.net.au</email></para> - </listitem> - - <listitem> - <para>David Leonard <email>d@scry.dstc.edu.au</email></para> - </listitem> - - <listitem> - <para>David Malone <email>dwmalone@maths.tcd.ie</email></para> - </listitem> - - <listitem> - <para>David Muir Sharnoff <email>muir@idiom.com</email></para> - </listitem> - - <listitem> - <para>David S. Miller <email>davem@jenolan.rutgers.edu</email></para> - </listitem> - - <listitem> - <para>David Wolfskill <email>dhw@whistle.com</email></para> - </listitem> - - <listitem> - <para>Dean Gaudet <email>dgaudet@arctic.org</email></para> - </listitem> - - <listitem> - <para>Dean Huxley <email>dean@fsa.ca</email></para> - </listitem> - - <listitem> - <para>Denis Fortin <email>unknown</email></para> - </listitem> - - <listitem> - <para>Dennis Glatting - <email>dennis.glatting@software-munitions.com</email></para> - </listitem> - - <listitem> - <para>Denton Gentry <email>denny1@home.com</email></para> - </listitem> - - <listitem> - <para>Derek Inksetter <email>derek@saidev.com</email></para> - </listitem> - - <listitem> - <para>Dima Sivachenko <email>dima@Chg.RU</email></para> - </listitem> - - <listitem> - <para>Dirk Keunecke <email>dk@panda.rhein-main.de</email></para> - </listitem> - - <listitem> - <para>Dirk Nehrling <email>nerle@pdv.de</email></para> - </listitem> - - <listitem> - <para>Dmitry Khrustalev <email>dima@xyzzy.machaon.ru</email></para> - </listitem> - - <listitem> - <para>Dmitry Kohmanyuk <email>dk@farm.org</email></para> - </listitem> - - <listitem> - <para>Dom Mitchell <email>dom@myrddin.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Dominik Brettnacher <email>domi@saargate.de</email></para> - </listitem> - - <listitem> - <para>Don Croyle <email>croyle@gelemna.ft-wayne.in.us</email></para> - </listitem> - - <listitem> - <para>&a.whiteside;</para> - </listitem> - - <listitem> - <para>Don Morrison <email>dmorrisn@u.washington.edu</email></para> - </listitem> - - <listitem> - <para>Don Yuniskis <email>dgy@rtd.com</email></para> - </listitem> - - <listitem> - <para>Donald Maddox <email>dmaddox@conterra.com</email></para> - </listitem> - - <listitem> - <para>Doug Barton <email>studded@dal.net</email></para> - </listitem> - - <listitem> - <para>Douglas Ambrisko <email>ambrisko@whistle.com</email></para> - </listitem> - - <listitem> - <para>Douglas Carmichael <email>dcarmich@mcs.com</email></para> - </listitem> - - <listitem> - <para>Douglas Crosher <email>dtc@scrooge.ee.swin.oz.au</email></para> - </listitem> - - <listitem> - <para>Drew Derbyshire <email>ahd@kew.com</email></para> - </listitem> - - <listitem> - <para>Duncan Barclay <email>dmlb@ragnet.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Dustin Sallings <email>dustin@spy.net</email></para> - </listitem> - - <listitem> - <para>Eckart "Isegrim" Hofmann - <email>Isegrim@Wunder-Nett.org</email></para> - </listitem> - - <listitem> - <para>Ed Gold - <email>vegold01@starbase.spd.louisville.edu</email></para> - </listitem> - - <listitem> - <para>Ed Hudson <email>elh@p5.spnet.com</email></para> - </listitem> - - <listitem> - <para>Edward Wang <email>edward@edcom.com</email></para> - </listitem> - - <listitem> - <para>Edwin Groothus <email>edwin@nwm.wan.philips.com</email></para> - </listitem> - - <listitem> - <para>Eiji-usagi-MATSUmoto <email>usagi@clave.gr.jp</email></para> - </listitem> - - <listitem> - <para>ELISA Font Project</para> - </listitem> - - <listitem> - <para>Elmar Bartel - <email>bartel@informatik.tu-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Eric A. Griff <email>eagriff@global2000.net</email></para> - </listitem> - - <listitem> - <para>Eric Blood <email>eblood@cs.unr.edu</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Eric J. Schwertfeger <email>eric@cybernut.com</email></para> - </listitem> - - <listitem> - <para>Eric L. Hernes <email>erich@lodgenet.com</email></para> - </listitem> - - <listitem> - <para>Eric P. Scott <email>eps@sirius.com</email></para> - </listitem> - - <listitem> - <para>Eric Sprinkle <email>eric@ennovatenetworks.com</email></para> - </listitem> - - <listitem> - <para>Erich Stefan Boleyn <email>erich@uruk.org</email></para> - </listitem> - - <listitem> - <para>Erik E. Rantapaa <email>rantapaa@math.umn.edu</email></para> - </listitem> - - <listitem> - <para>Erik H. Moe <email>ehm@cris.com</email></para> - </listitem> - - <listitem> - <para>Ernst Winter <email>ewinter@lobo.muc.de</email></para> - </listitem> - - <listitem> - <para>Espen Skoglund <email>espensk@stud.cs.uit.no></email></para> - </listitem> - - <listitem> - <para>Eugene M. Kim <email>astralblue@usa.net</email></para> - </listitem> - - <listitem> - <para>Eugene Radchenko <email>genie@qsar.chem.msu.su</email></para> - </listitem> - - <listitem> - <para>Evan Champion <email>evanc@synapse.net</email></para> - </listitem> - - <listitem> - <para>Faried Nawaz <email>fn@Hungry.COM</email></para> - </listitem> - - <listitem> - <para>Flemming Jacobsen <email>fj@tfs.com</email></para> - </listitem> - - <listitem> - <para>Fong-Ching Liaw <email>fong@juniper.net</email></para> - </listitem> - - <listitem> - <para>Francis M J Hsieh <email>mjshieh@life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Bartels <email>knarf@camelot.de</email></para> - </listitem> - - <listitem> - <para>Frank Chen Hsiung Chan - <email>frankch@waru.life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Durda IV <email>uhclem@nemesis.lonestar.org</email></para> - </listitem> - - <listitem> - <para>Frank MacLachlan <email>fpm@n2.net</email></para> - </listitem> - - <listitem> - <para>Frank Nobis <email>fn@Radio-do.de</email></para> - </listitem> - - <listitem> - <para>Frank Volf <email>volf@oasis.IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>Frank ten Wolde <email>franky@pinewood.nl</email></para> - </listitem> - - <listitem> - <para>Frank van der Linden <email>frank@fwi.uva.nl</email></para> - </listitem> - - <listitem> - <para>Fred Cawthorne <email>fcawth@jjarray.umn.edu</email></para> - </listitem> - - <listitem> - <para>Fred Gilham <email>gilham@csl.sri.com</email></para> - </listitem> - - <listitem> - <para>Fred Templin <email>templin@erg.sri.com</email></para> - </listitem> - - <listitem> - <para>Frederick Earl Gray <email>fgray@rice.edu</email></para> - </listitem> - - <listitem> - <para>FUJIMOTO Kensaku - <email>fujimoto@oscar.elec.waseda.ac.jp</email></para> - </listitem> - - <listitem> - <para>FUJISHIMA Satsuki <email>k5@respo.or.jp</email></para> - </listitem> - - <listitem> - <para>FURUSAWA Kazuhisa - <email>furusawa@com.cs.osakafu-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Gabor Kincses <email>gabor@acm.org</email></para> - </listitem> - - <listitem> - <para>Gabor Zahemszky <email>zgabor@CoDe.hu</email></para> - </listitem> - - <listitem> - <para>G. Adam Stanislav<email>adam@whizkidtech.net</email></para> - </listitem> - - <listitem> - <para>Garance A Drosehn <email>gad@eclipse.its.rpi.edu</email></para> - </listitem> - - <listitem> - <para>Gareth McCaughan <email>gjm11@dpmms.cam.ac.uk</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Gary J. <email>garyj@rks32.pcs.dec.com</email></para> - </listitem> - - <listitem> - <para>Gary Kline <email>kline@thought.org</email></para> - </listitem> - - <listitem> - <para>Gaspar Chilingarov <email>nightmar@lemming.acc.am</email></para> - </listitem> - - <listitem> - <para>Gea-Suan Lin <email>gsl@tpts4.seed.net.tw</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Georg Wagner <email>georg.wagner@ubs.com</email></para> - </listitem> - - <listitem> - <para>Gerard Roudier <email>groudier@club-internet.fr</email></para> - </listitem> - - <listitem> - <para>Gianmarco Giovannelli - <email>gmarco@giovannelli.it</email></para> - </listitem> - - <listitem> - <para>Gil Kloepfer Jr. <email>gil@limbic.ssdl.com</email></para> - </listitem> - - <listitem> - <para>Gilad Rom <email>rom_glsa@ein-hashofet.co.il</email></para> - </listitem> - - <listitem> - <para>Ginga Kawaguti - <email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Giles Lean <email>giles@nemeton.com.au</email></para> - </listitem> - - <listitem> - <para>Glen Foster <email>gfoster@gfoster.com</email></para> - </listitem> - - <listitem> - <para>Glenn Johnson <email>gljohns@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>Godmar Back <email>gback@facility.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Gord Matzigkeit <email>gord@enci.ucalgary.ca</email></para> - </listitem> - - <listitem> - <para>Gordon Greeff <email>gvg@uunet.co.za</email></para> - </listitem> - - <listitem> - <para>Graham Wheeler <email>gram@cdsec.com</email></para> - </listitem> - - <listitem> - <para>Greg A. Woods <email>woods@zeus.leitch.com</email></para> - </listitem> - - <listitem> - <para>Greg Ansley <email>gja@ansley.com</email></para> - </listitem> - - <listitem> - <para>Greg Troxel <email>gdt@ir.bbn.com</email></para> - </listitem> - - <listitem> - <para>Greg Ungerer <email>gerg@stallion.oz.au</email></para> - </listitem> - - <listitem> - <para>Gregory Bond <email>gnb@itga.com.au</email></para> - </listitem> - - <listitem> - <para>Gregory D. Moncreaff - <email>moncrg@bt340707.res.ray.com</email></para> - </listitem> - - <listitem> - <para>Guy Harris <email>guy@netapp.com</email></para> - </listitem> - - <listitem> - <para>Guy Helmer <email>ghelmer@cs.iastate.edu</email></para> - </listitem> - - <listitem> - <para>HAMADA Naoki <email>hamada@astec.co.jp</email></para> - </listitem> - - <listitem> - <para>HONDA Yasuhiro - <email>honda@kashio.info.mie-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>HOSOBUCHI Noriyuki <email>hoso@buchi.tama.or.jp</email></para> - </listitem> - - <listitem> - <para>Hannu Savolainen <email>hannu@voxware.pp.fi</email></para> - </listitem> - - <listitem> - <para>Hans Huebner <email>hans@artcom.de</email></para> - </listitem> - - <listitem> - <para>Hans Petter Bieker <email>zerium@webindex.no</email></para> - </listitem> - - <listitem> - <para>Hans Zuidam <email>hans@brandinnovators.com</email></para> - </listitem> - - <listitem> - <para>Harlan Stenn <email>Harlan.Stenn@pfcs.com</email></para> - </listitem> - - <listitem> - <para>Harold Barker <email>hbarker@dsms.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes - <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Heikki Suonsivu <email>hsu@cs.hut.fi</email></para> - </listitem> - - <listitem> - <para>Heiko W. Rupp <email>unknown</email></para> - </listitem> - - <listitem> - <para>Helmut F. Wirth <email>hfwirth@ping.at</email></para> - </listitem> - - <listitem> - <para>Henrik Vestergaard Draboel - <email>hvd@terry.ping.dk</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl <email>hpeyerl@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Hideaki Ohmon <email>ohmon@tom.sfc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hidekazu Kuroki <email>hidekazu@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hideki Yamamoto <email>hyama@acm.org</email></para> - </listitem> - - <listitem> - <para>Hideyuki Suzuki - <email>hideyuki@sat.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hirayama Issei <email>iss@mail.wbs.ne.jp</email></para> - </listitem> - - <listitem> - <para>Hiroaki Sakai <email>sakai@miya.ee.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hiroharu Tamaru <email>tamaru@ap.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hironori Ikura <email>hikura@kaisei.org</email></para> - </listitem> - - <listitem> - <para>Hiroshi Nishikawa <email>nis@pluto.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>Hiroya Tsubakimoto <email>unknown</email></para> - </listitem> - - <listitem> - <para>Holger Veit <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Holm Tiffe <email>holm@geophysik.tu-freiberg.de</email></para> - </listitem> - - <listitem> - <para>Horance Chou - <email>horance@freedom.ie.cycu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Horihiro Kumagai <email>kuma@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>HOTARU-YA <email>hotaru@tail.net</email></para> - </listitem> - - <listitem> - <para>Hr.Ladavac <email>lada@ws2301.gud.siemens.co.at</email></para> - </listitem> - - <listitem> - <para>Hubert Feyrer <email>hubertf@NetBSD.ORG</email></para> - </listitem> - - <listitem> - <para>Hugh F. Mahon <email>hugh@nsmdserv.cnd.hp.com</email></para> - </listitem> - - <listitem> - <para>Hugh Mahon <email>h_mahon@fc.hp.com</email></para> - </listitem> - - <listitem> - <para>Hung-Chi Chu <email>hcchu@r350.ee.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>IMAI Takeshi <email>take-i@ceres.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>IMAMURA Tomoaki - <email>tomoak-i@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>Ian Dowse <email>iedowse@maths.tcd.ie</email></para> - </listitem> - - <listitem> - <para>Ian Holland <email>ianh@tortuga.com.au</email></para> - </listitem> - - <listitem> - <para>Ian Struble <email>ian@broken.net</email></para> - </listitem> - - <listitem> - <para>Ian Vaudrey <email>i.vaudrey@bigfoot.com</email></para> - </listitem> - - <listitem> - <para>Igor Khasilev <email>igor@jabber.paco.odessa.ua</email></para> - </listitem> - - <listitem> - <para>Igor Roshchin <email>str@giganda.komkon.org</email></para> - </listitem> - - <listitem> - <para>Igor Sviridov <email>siac@ua.net</email></para> - </listitem> - - <listitem> - <para>Igor Vinokurov <email>igor@zynaps.ru</email></para> - </listitem> - - <listitem> - <para>Ikuo Nakagawa <email>ikuo@isl.intec.co.jp</email></para> - </listitem> - - <listitem> - <para>Ilya V. Komarov <email>mur@lynx.ru</email></para> - </listitem> - - <listitem> - <para>Issei Suzuki <email>issei@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Itsuro Saito <email>saito@miv.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>J. Bryant <email>jbryant@argus.flash.net</email></para> - </listitem> - - <listitem> - <para>J. David Lowe <email>lowe@saturn5.com</email></para> - </listitem> - - <listitem> - <para>J. Han <email>hjh@best.com</email></para> - </listitem> - - <listitem> - <para>J. Hawk <email>jhawk@MIT.EDU</email></para> - </listitem> - - <listitem> - <para>J.T. Conklin <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>J.T. Jang <email>keith@email.gcn.net.tw</email></para> - </listitem> - - <listitem> - <para>Jack <email>jack@zeus.xtalwind.net</email></para> - </listitem> - - <listitem> - <para>Jacob Bohn Lorensen <email>jacob@jblhome.ping.mk</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>Jake Burkholder <email>jake@checker.org</email></para> - </listitem> - - <listitem> - <para>Jake Hamby <email>jehamby@lightside.com</email></para> - </listitem> - - <listitem> - <para>James Clark <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James D. Stewart <email>jds@c4systm.com</email></para> - </listitem> - - <listitem> - <para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James Raynard - <email>fhackers@jraynard.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>James T. Liu <email>jtliu@phlebas.rockefeller.edu</email></para> - </listitem> - - <listitem> - <para>James da Silva <email>jds@cs.umd.edu</email></para> - </listitem> - - <listitem> - <para>Jan Conard - <email>charly@fachschaften.tu-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Jan Koum <email>jkb@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Janick Taillandier - <email>Janick.Taillandier@ratp.fr</email></para> - </listitem> - - <listitem> - <para>Janusz Kokot <email>janek@gaja.ipan.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Jarle Greipsland <email>jarle@idt.unit.no</email></para> - </listitem> - - <listitem> - <para>Jason Garman <email>init@risen.org</email></para> - </listitem> - - <listitem> - <para>Jason Thorpe <email>thorpej@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Jason Wright <email>jason@OpenBSD.org</email></para> - </listitem> - - <listitem> - <para>Jason Young - <email>doogie@forbidden-donut.anet-stl.com</email></para> - </listitem> - - <listitem> - <para>Javier Martin Rueda <email>jmrueda@diatel.upm.es</email></para> - </listitem> - - <listitem> - <para>Jay Fenlason <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jaye Mathisen <email>mrcpu@cdsnet.net</email></para> - </listitem> - - <listitem> - <para>Jeff Bartig <email>jeffb@doit.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Jeff Forys <email>jeff@forys.cranbury.nj.us</email></para> - </listitem> - - <listitem> - <para>Jeff Kletsky <email>Jeff@Wagsky.com</email></para> - </listitem> - - <listitem> - <para>Jeffrey Evans <email>evans@scnc.k12.mi.us</email></para> - </listitem> - - <listitem> - <para>Jeffrey Wheat <email>jeff@cetlink.net</email></para> - </listitem> - - <listitem> - <para>Jens Schweikhardt <email>schweikh@noc.dfn.d</email></para> - </listitem> - - <listitem> - <para>Jeremy Allison <email>jallison@whistle.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Chatfield <email>jdc@xinside.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Lea <email>reg@shale.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Jeremy Prior <email>unknown</email></para> - </listitem> - - <listitem> - <para>Jeroen Ruigrok/Asmodai <email>asmodai@wxs.nl</email></para> - </listitem> - - <listitem> - <para>Jesse Rosenstock <email>jmr@ugcs.caltech.edu</email></para> - </listitem> - - <listitem> - <para>Jian-Da Li <email>jdli@csie.nctu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Jim Babb <email>babb@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Jim Binkley <email>jrb@cs.pdx.edu</email></para> - </listitem> - - <listitem> - <para>Jim Carroll <email>jim@carroll.com</email></para> - </listitem> - - <listitem> - <para>Jim Flowers <email>jflowers@ezo.net</email></para> - </listitem> - - <listitem> - <para>Jim Leppek <email>jleppek@harris.com</email></para> - </listitem> - - <listitem> - <para>Jim Lowe <email>james@cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>Jim Mattson <email>jmattson@sonic.net</email></para> - </listitem> - - <listitem> - <para>Jim Mercer <email>jim@komodo.reptiles.org</email></para> - </listitem> - - <listitem> - <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jimbo Bahooli - <email>griffin@blackhole.iceworld.org</email></para> - </listitem> - - <listitem> - <para>Jin Guojun <email>jin@george.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Joachim Kuebart <email>unknown</email></para> - </listitem> - - <listitem> - <para>Joao Carlos Mendes Luis <email>jonny@jonny.eng.br</email></para> - </listitem> - - <listitem> - <para>Jochen Pohl <email>jpo.drs@sni.de</email></para> - </listitem> - - <listitem> - <para>Joe "Marcus" Clarke <email>marcus@miami.edu</email></para> - </listitem> - - <listitem> - <para>Joe Abley <email>jabley@clear.co.nz</email></para> - </listitem> - - <listitem> - <para>Joe Jih-Shian Lu <email>jslu@dns.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Joe Orthoefer <email>j_orthoefer@tia.net</email></para> - </listitem> - - <listitem> - <para>Joe Traister <email>traister@mojozone.org</email></para> - </listitem> - - <listitem> - <para>Joel Faedi <email>Joel.Faedi@esial.u-nancy.fr</email></para> - </listitem> - - <listitem> - <para>Joel Ray Holveck <email>joelh@gnu.org</email></para> - </listitem> - - <listitem> - <para>Joel Sutton <email>sutton@aardvark.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Johan Granlund <email>johan@granlund.nu</email></para> - </listitem> - - <listitem> - <para>Johan Karlsson <email>k@numeri.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Johan Larsson <email>johan@moon.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Johann Tonsing <email>jtonsing@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Johannes Helander <email>unknown</email></para> - </listitem> - - <listitem> - <para>Johannes Stille <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Baldwin <email>jobaldwi@vt.edu</email></para> - </listitem> - - <listitem> - <para>John Beckett <email>jbeckett@southern.edu</email></para> - </listitem> - - <listitem> - <para>John Beukema <email>jbeukema@hk.super.net</email></para> - </listitem> - - <listitem> - <para>John Brezak <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Capo <email>jc@irbs.com</email></para> - </listitem> - - <listitem> - <para>John F. Woods <email>jfw@jfwhome.funhouse.com</email></para> - </listitem> - - <listitem> - <para>John Goerzen - <email>jgoerzen@alexanderwohl.complete.org</email></para> - </listitem> - - <listitem> - <para>John Hay <email>jhay@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>John Heidemann <email>johnh@isi.edu</email></para> - </listitem> - - <listitem> - <para>John Hood <email>cgull@owl.org</email></para> - </listitem> - - <listitem> - <para>John Kohl <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Lind <email>john@starfire.mn.org</email></para> - </listitem> - - <listitem> - <para>John Mackin <email>john@physiol.su.oz.au</email></para> - </listitem> - - <listitem> - <para>John P <email>johnp@lodgenet.com</email></para> - </listitem> - - <listitem> - <para>John Perry <email>perry@vishnu.alias.net</email></para> - </listitem> - - <listitem> - <para>John Preisler <email>john@vapornet.com</email></para> - </listitem> - - <listitem> - <para>John Rochester <email>jr@cs.mun.ca</email></para> - </listitem> - - <listitem> - <para>John Sadler <email>john_sadler@alum.mit.edu</email></para> - </listitem> - - <listitem> - <para>John Saunders <email>john@pacer.nlc.net.au</email></para> - </listitem> - - <listitem> - <para>John W. DeBoskey <email>jwd@unx.sas.com</email></para> - </listitem> - - <listitem> - <para>John Wehle <email>john@feith.com</email></para> - </listitem> - - <listitem> - <para>John Woods <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Jon Morgan <email>morgan@terminus.trailblazer.com</email></para> - </listitem> - - <listitem> - <para>Jonathan H N Chin <email>jc254@newton.cam.ac.uk</email></para> - </listitem> - - <listitem> - <para>Jonathan Hanna - <email>jh@pc-21490.bc.rogers.wave.ca</email></para> - </listitem> - - <listitem> - <para>Jorge Goncalves <email>j@bug.fe.up.pt</email></para> - </listitem> - - <listitem> - <para>Jorge M. Goncalves <email>ee96199@tom.fe.up.pt</email></para> - </listitem> - - <listitem> - <para>Jos Backus <email>jbackus@plex.nl</email></para> - </listitem> - - <listitem> - <para>Jose M. Alcaide <email>jose@we.lc.ehu.es</email></para> - </listitem> - - <listitem> - <para>Jose Marques <email>jose@nobody.org</email></para> - </listitem> - - <listitem> - <para>Josef Grosch - <email>jgrosch@superior.mooseriver.com</email></para> - </listitem> - - <listitem> - <para>Josef Karthauser <email>joe@uk.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Joseph Stein <email>joes@wstein.com</email></para> - </listitem> - - <listitem> - <para>Josh Gilliam <email>josh@quick.net</email></para> - </listitem> - - <listitem> - <para>Josh Tiefenbach <email>josh@ican.net</email></para> - </listitem> - - <listitem> - <para>Juergen Lock <email>nox@jelal.hb.north.de</email></para> - </listitem> - - <listitem> - <para>Juha Inkari <email>inkari@cc.hut.fi</email></para> - </listitem> - - <listitem> - <para>Jukka A. Ukkonen <email>jua@iki.fi</email></para> - </listitem> - - <listitem> - <para>Julian Assange <email>proff@suburbia.net</email></para> - </listitem> - - <listitem> - <para>Julian Coleman <email>j.d.coleman@ncl.ac.uk</email></para> - </listitem> - - <listitem> - <para>&a.jhs</para> - </listitem> - - <listitem> - <para>Julian Jenkins <email>kaveman@magna.com.au</email></para> - </listitem> - - <listitem> - <para>Junichi Satoh <email>junichi@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Junji SAKAI <email>sakai@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Junya WATANABE <email>junya-w@remus.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>K.Higashino <email>a00303@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>KUNISHIMA Takeo <email>kunishi@c.oka-pu.ac.jp</email></para> - </listitem> - - <listitem> - <para>Kai Vorma <email>vode@snakemail.hut.fi</email></para> - </listitem> - - <listitem> - <para>Kaleb S. Keithley <email>kaleb@ics.com</email></para> - </listitem> - - <listitem> - <para>Kaneda Hiloshi <email>vanitas@ma3.seikyou.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kapil Chowksey <email>kchowksey@hss.hns.com</email></para> - </listitem> - - <listitem> - <para>Karl Denninger <email>karl@mcs.com</email></para> - </listitem> - - <listitem> - <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer <email>karl@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Kato Takenori - <email>kato@eclogite.eps.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Kawanobe Koh <email>kawanobe@st.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Kazuhiko Kiriyama <email>kiri@kiri.toba-cmt.ac.jp</email></para> - </listitem> - - <listitem> - <para>Kazuo Horikawa <email>horikawa@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Kees Jan Koster <email>kjk1@ukc.ac.uk</email></para> - </listitem> - - <listitem> - <para>Keith Bostic <email>bostic@bostic.com</email></para> - </listitem> - - <listitem> - <para>Keith E. Walker <email>unknown</email></para> - </listitem> - - <listitem> - <para>Keith Moore <email>unknown</email></para> - </listitem> - - <listitem> - <para>Keith Sklower <email>unknown</email></para> - </listitem> - - <listitem> - <para>Kelly Yancey <email>kbyanc@posi.net</email></para> - </listitem> - - <listitem> - <para>Ken Hornstein <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ken Key <email>key@cs.utk.edu</email></para> - </listitem> - - <listitem> - <para>Ken Mayer <email>kmayer@freegate.com</email></para> - </listitem> - - <listitem> - <para>Kenji Saito <email>marukun@mx2.nisiq.net</email></para> - </listitem> - - <listitem> - <para>Kenji Tomita <email>tommyk@da2.so-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Kenneth Furge <email>kenneth.furge@us.endress.com</email></para> - </listitem> - - <listitem> - <para>Kenneth Monville <email>desmo@bandwidth.org</email></para> - </listitem> - - <listitem> - <para>Kenneth R. Westerback <email>krw@tcn.net</email></para> - </listitem> - - <listitem> - <para>Kenneth Stailey <email>kstailey@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kent Vander Velden <email>graphix@iastate.edu</email></para> - </listitem> - - <listitem> - <para>Kentaro Inagaki <email>JBD01226@niftyserve.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kevin Bracey <email>kbracey@art.acorn.co.uk</email></para> - </listitem> - - <listitem> - <para>Kevin Day <email>toasty@dragondata.com</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey <email>kml@nas.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Kevin Lo<email>kevlo@hello.com.tw</email></para> - </listitem> - - <listitem> - <para>Kevin Street <email>street@iname.com</email></para> - </listitem> - - <listitem> - <para>Kevin Van Maren <email>vanmaren@fast.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Kiroh HARADA <email>kiroh@kh.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Klaus Klein <email>kleink@layla.inka.de</email></para> - </listitem> - - <listitem> - <para>Klaus-J. Wolf <email>Yanestra@t-online.de</email></para> - </listitem> - - <listitem> - <para>Koichi Sato <email>copan@ppp.fastnet.or.jp</email></para> - </listitem> - - <listitem> - <para>Kostya Lukin <email>lukin@okbmei.msk.su</email></para> - </listitem> - - <listitem> - <para>Kouichi Hirabayashi <email>kh@mogami-wire.co.jp</email></para> - </listitem> - - <listitem> - <para>Kurt D. Zeilenga <email>Kurt@Boolean.NET</email></para> - </listitem> - - <listitem> - <para>Kurt Olsen <email>kurto@tiny.mcs.usu.edu</email></para> - </listitem> - - <listitem> - <para>L. Jonas Olsson - <email>ljo@ljo-slip.DIALIN.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Lars Köller - <email>Lars.Koeller@Uni-Bielefeld.DE</email></para> - </listitem> - - <listitem> - <para>Larry Altneu <email>larry@ALR.COM</email></para> - </listitem> - - <listitem> - <para>Laurence Lopez <email>lopez@mv.mv.com</email></para> - </listitem> - - <listitem> - <para>Lee Cremeans <email>lcremean@tidalwave.net</email></para> - </listitem> - - <listitem> - <para>Liang Tai-hwa - <email>avatar@www.mmlab.cse.yzu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Lon Willett <email>lon%softt.uucp@math.utah.edu</email></para> - </listitem> - - <listitem> - <para>Louis A. Mamakos <email>louie@TransSys.COM</email></para> - </listitem> - - <listitem> - <para>Louis Mamakos <email>loiue@TransSys.com</email></para> - </listitem> - - <listitem> - <para>Lucas James <email>Lucas.James@ldjpc.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Lyndon Nerenberg <email>lyndon@orthanc.com</email></para> - </listitem> - - <listitem> - <para>M.C. Wong <email>unknown</email></para> - </listitem> - - <listitem> - <para>MANTANI Nobutaka <email>nobutaka@nobutaka.com</email></para> - </listitem> - - <listitem> - <para>MIHIRA Sanpei Yoshiro <email>sanpei@sanpei.org</email></para> - </listitem> - - <listitem> - <para>MITA Yoshio <email>mita@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>MITSUNAGA Noriaki - <email>mitchy@er.ams.eng.osaka-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>MOROHOSHI Akihiko <email>moro@race.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Magnus Enbom <email>dot@tinto.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Mahesh Neelakanta <email>mahesh@gcomm.com</email></para> - </listitem> - - <listitem> - <para>Makoto MATSUSHITA <email>matusita@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Makoto WATANABE - <email>watanabe@zlab.phys.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Malte Lance <email>malte.lance@gmx.net</email></para> - </listitem> - - <listitem> - <para>Manu Iyengar - <email>iyengar@grunthos.pscwa.psca.com</email></para> - </listitem> - - <listitem> - <para>Marc Frajola <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Marc Ramirez <email>mrami@mramirez.sy.yale.edu</email></para> - </listitem> - - <listitem> - <para>Marc Slemko <email>marcs@znep.com</email></para> - </listitem> - - <listitem> - <para>Marc van Kempen <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>Marc van Woerkom <email>van.woerkom@netcologne.de</email></para> - </listitem> - - <listitem> - <para>Marcel Moolenaar <email>marcel@scc.nl</email></para> - </listitem> - - <listitem> - <para>Mario Sergio Fujikawa Ferreira - <email>lioux@gns.com.br</email></para> - </listitem> - - <listitem> - <para>Mark Andrews <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mark Cammidge <email>mark@gmtunx.ee.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Mark Diekhans <email>markd@grizzly.com</email></para> - </listitem> - - <listitem> - <para>Mark Huizer <email>xaa@stack.nl</email></para> - </listitem> - - <listitem> - <para>Mark J. Taylor <email>mtaylor@cybernet.com</email></para> - </listitem> - - <listitem> - <para>Mark Krentel <email>krentel@rice.edu</email></para> - </listitem> - - <listitem> - <para>Mark Mayo <email>markm@vmunix.com</email></para> - </listitem> - - <listitem> - <para>Mark Thompson <email>thompson@tgsoft.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email></para> - </listitem> - - <listitem> - <para>Mark Treacy <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mark Valentine <email>mark@linus.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Martin Birgmeier</para> - </listitem> - - <listitem> - <para>Martin Ibert <email>mib@ppe.bb-data.de</email></para> - </listitem> - - <listitem> - <para>Martin Kammerhofer <email>dada@sbox.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Martin Renters <email>martin@tdc.on.ca</email></para> - </listitem> - - <listitem> - <para>Martti Kuparinen - <email>martti.kuparinen@ericsson.com</email></para> - </listitem> - - <listitem> - <para>Masachika ISHIZUKA - <email>ishizuka@isis.min.ntt.jp</email></para> - </listitem> - - <listitem> - <para>Mas.TAKEMURA <email>unknown</email></para> - </listitem> - - <listitem> - <para>Masafumi NAKANE <email>max@wide.ad.jp</email></para> - </listitem> - - <listitem> - <para>Masahiro Sekiguchi - <email>seki@sysrap.cs.fujitsu.co.jp</email></para> - </listitem> - - <listitem> - <para>Masanobu Saitoh <email>msaitoh@spa.is.uec.ac.jp</email></para> - </listitem> - - <listitem> - <para>Masanori Kanaoka <email>kana@saijo.mke.mei.co.jp</email></para> - </listitem> - - <listitem> - <para>Masanori Kiriake <email>seiken@ARGV.AC</email></para> - </listitem> - - <listitem> - <para>Masatoshi TAMURA - <email>tamrin@shinzan.kuee.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Mats Lofkvist <email>mal@algonet.se</email></para> - </listitem> - - <listitem> - <para>Matt Bartley <email>mbartley@lear35.cytex.com</email></para> - </listitem> - - <listitem> - <para>Matt Thomas <email>matt@3am-software.com</email></para> - </listitem> - - <listitem> - <para>Matt White <email>mwhite+@CMU.EDU</email></para> - </listitem> - - <listitem> - <para>Matthew C. Mead <email>mmead@Glock.COM</email></para> - </listitem> - - <listitem> - <para>Matthew Cashdollar <email>mattc@rfcnet.com</email></para> - </listitem> - - <listitem> - <para>Matthew Flatt <email>mflatt@cs.rice.edu</email></para> - </listitem> - - <listitem> - <para>Matthew Fuller <email>fullermd@futuresouth.com</email></para> - </listitem> - - <listitem> - <para>Matthew Stein <email>matt@bdd.net</email></para> - </listitem> - - <listitem> - <para>Matthias Pfaller <email>leo@dachau.marco.de</email></para> - </listitem> - - <listitem> - <para>Matthias Scheler <email>tron@netbsd.org</email></para> - </listitem> - - <listitem> - <para>Mattias Gronlund - <email>Mattias.Gronlund@sa.erisoft.se</email></para> - </listitem> - - <listitem> - <para>Mattias Pantzare <email>pantzer@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Maurice Castro - <email>maurice@planet.serc.rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Max Euston <email>meuston@jmrodgers.com</email></para> - </listitem> - - <listitem> - <para>Max Khon <email>fjoe@husky.iclub.nsu.ru</email></para> - </listitem> - - <listitem> - <para>Maxim Bolotin <email>max@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Maxim V. Sobolev <email>sobomax@altavista.net</email></para> - </listitem> - - <listitem> - <para>Micha Class - <email>michael_class@hpbbse.bbn.hp.com</email></para> - </listitem> - - <listitem> - <para>Michael Butler <email>imb@scgt.oz.au</email></para> - </listitem> - - <listitem> - <para>Michael Butschky <email>butsch@computi.erols.com</email></para> - </listitem> - - <listitem> - <para>Michael Clay <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Elbel <email>me@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Michael Hancock <email>michaelh@cet.co.jp</email></para> - </listitem> - - <listitem> - <para>Michael Hohmuth <email>hohmuth@inf.tu-dresden.de</email></para> - </listitem> - - <listitem> - <para>Michael Perlman <email>canuck@caam.rice.edu</email></para> - </listitem> - - <listitem> - <para>Michael Petry <email>petry@netwolf.NetMasters.com</email></para> - </listitem> - - <listitem> - <para>Michael Reifenberger <email>root@totum.plaut.de</email></para> - </listitem> - - <listitem> - <para>Michael Sardo <email>jaeger16@yahoo.com</email></para> - </listitem> - - <listitem> - <para>Michael Searle <email>searle@longacre.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Michal Listos <email>mcl@Amnesiac.123.org</email></para> - </listitem> - - <listitem> - <para>Michio Karl Jinbo - <email>karl@marcer.nagaokaut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Miguel Angel Sagreras - <email>msagre@cactus.fi.uba.ar</email></para> - </listitem> - - <listitem> - <para>Mihoko Tanaka <email>m_tonaka@pa.yokogawa.co.jp</email></para> - </listitem> - - <listitem> - <para>Mika Nystrom <email>mika@cs.caltech.edu</email></para> - </listitem> - - <listitem> - <para>Mikael Hybsch <email>micke@dynas.se</email></para> - </listitem> - - <listitem> - <para>Mikael Karpberg - <email>karpen@ocean.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Mike Del <email>repenting@hotmail.com</email></para> - </listitem> - - <listitem> - <para>Mike Durian <email>durian@plutotech.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Mike E. Matsnev <email>mike@azog.cs.msu.su</email></para> - </listitem> - - <listitem> - <para>Mike Evans <email>mevans@candle.com</email></para> - </listitem> - - <listitem> - <para>Mike Grupenhoff <email>kashmir@umiacs.umd.edu</email></para> - </listitem> - - <listitem> - <para>Mike Hibler <email>mike@marker.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Mike Karels <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mike McGaughey <email>mmcg@cs.monash.edu.au</email></para> - </listitem> - - <listitem> - <para>Mike Meyer <email>mwm@shiva.the-park.com</email></para> - </listitem> - - <listitem> - <para>Mike Mitchell <email>mitchell@ref.tfs.com</email></para> - </listitem> - - <listitem> - <para>Mike Murphy <email>mrm@alpharel.com</email></para> - </listitem> - - <listitem> - <para>Mike Peck <email>mike@binghamton.edu</email></para> - </listitem> - - <listitem> - <para>Mike Spengler <email>mks@msc.edu</email></para> - </listitem> - - <listitem> - <para>Mikhail A. Sokolov <email>mishania@demos.su</email></para> - </listitem> - - <listitem> - <para>Mikhail Teterin <email>mi@aldan.ziplink.net</email></para> - </listitem> - - <listitem> - <para>Ming-I Hseh <email>PA@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>Mitsuru IWASAKI <email>iwasaki@pc.jaring.my</email></para> - </listitem> - - <listitem> - <para>Mitsuru Yoshida <email>mitsuru@riken.go.jp</email></para> - </listitem> - - <listitem> - <para>Monte Mitzelfelt <email>monte@gonefishing.org</email></para> - </listitem> - - <listitem> - <para>Morgan Davis <email>root@io.cts.com</email></para> - </listitem> - - <listitem> - <para>Mostyn Lewis <email>mostyn@mrl.com</email></para> - </listitem> - - <listitem> - <para>Motomichi Matsuzaki <email>mzaki@e-mail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Motoyuki Kasahara <email>m-kasahr@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Motoyuki Konno <email>motoyuki@snipe.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Murray Stokely <email>murray@cdrom.com</email></para> - </listitem> - - <listitem> - <para>N.G.Smith <email>ngs@sesame.hensa.ac.uk</email></para> - </listitem> - - <listitem> - <para>NAGAO Tadaaki <email>nagao@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>NAKAJI Hiroyuki - <email>nakaji@tutrp.tut.ac.jp</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Kazushi <email>nkazushi@highway.or.jp</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Motonori - <email>motonori@econ.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>NIIMI Satoshi <email>sa2c@and.or.jp</email></para> - </listitem> - - <listitem> - <para>NOKUBI Hirotaka <email>h-nokubi@yyy.or.jp</email></para> - </listitem> - - <listitem> - <para>Nadav Eiron <email>nadav@barcode.co.il</email></para> - </listitem> - - <listitem> - <para>Nanbor Wang <email>nw1@cs.wustl.edu</email></para> - </listitem> - - <listitem> - <para>Naofumi Honda - <email>honda@Kururu.math.sci.hokudai.ac.jp</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Narvi <email>narvi@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Nathan Ahlstrom <email>nrahlstr@winternet.com</email></para> - </listitem> - - <listitem> - <para>Nathan Dorfman <email>nathan@rtfm.net</email></para> - </listitem> - - <listitem> - <para>Neal Fachan <email>kneel@ishiboo.com</email></para> - </listitem> - - <listitem> - <para>Neil Blakey-Milner <email>nbm@rucus.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Niall Smart <email>rotel@indigo.ie</email></para> - </listitem> - - <listitem> - <para>Nick Barnes <email>Nick.Barnes@pobox.com</email></para> - </listitem> - - <listitem> - <para>Nick Handel <email>nhandel@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Nick Hilliard <email>nick@foobar.org</email></para> - </listitem> - - <listitem> - <para>&a.nsayer;</para> - </listitem> - - <listitem> - <para>Nick Williams <email>njw@cs.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Nickolay N. Dudorov <email>nnd@itfs.nsk.su</email></para> - </listitem> - - <listitem> - <para>Niklas Hallqvist <email>niklas@filippa.appli.se</email></para> - </listitem> - - <listitem> - <para>Nisha Talagala <email>nisha@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>ZW6T-KND@j.asahi-net.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>adrian@virginia.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>alex@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>No Name <email>anto@netscape.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>bobson@egg.ics.nitch.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>bovynf@awe.be</email></para> - </listitem> - - <listitem> - <para>No Name <email>burg@is.ge.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>chris@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>No Name <email>colsen@usa.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>coredump@nervosa.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>dannyman@arh0300.urh.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>davids@SECNET.COM</email></para> - </listitem> - - <listitem> - <para>No Name <email>derek@free.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>devet@adv.IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>djv@bedford.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>dvv@sprint.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>enami@ba2.so-net.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>flash@eru.tubank.msk.su</email></para> - </listitem> - - <listitem> - <para>No Name <email>flash@hway.ru</email></para> - </listitem> - - <listitem> - <para>No Name <email>fn@pain.csrv.uidaho.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>gclarkii@netport.neosoft.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>gordon@sheaky.lonestar.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>graaf@iae.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>greg@greg.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>grossman@cygnus.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>gusw@fub46.zedat.fu-berlin.de</email></para> - </listitem> - - <listitem> - <para>No Name <email>hfir@math.rochester.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>hnokubi@yyy.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>iaint@css.tuu.utas.edu.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>invis@visi.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>ishisone@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>iverson@lionheart.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>jpt@magic.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>junker@jazz.snu.ac.kr</email></para> - </listitem> - - <listitem> - <para>No Name <email>k-sugyou@ccs.mt.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>kenji@reseau.toyonaka.osaka.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>kfurge@worldnet.att.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>lh@aus.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>lhecking@nmrc.ucc.ie</email></para> - </listitem> - - <listitem> - <para>No Name <email>mrgreen@mame.mu.oz.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>nakagawa@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>ohki@gssm.otsuka.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>owaki@st.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>pechter@shell.monmouth.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>pete@pelican.pelican.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>pritc003@maroon.tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>risner@stdio.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>roman@rpd.univ.kiev.ua</email></para> - </listitem> - - <listitem> - <para>No Name <email>root@ns2.redline.ru</email></para> - </listitem> - - <listitem> - <para>No Name <email>root@uglabgw.ug.cs.sunysb.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>stephen.ma@jtec.com.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>sumii@is.s.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>takas-su@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>tamone@eig.unige.ch</email></para> - </listitem> - - <listitem> - <para>No Name <email>tjevans@raleigh.ibm.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>tony-o@iij.ad.jp amurai@spec.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>torii@tcd.hitachi.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>uenami@imasy.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>uhlar@netlab.sk</email></para> - </listitem> - - <listitem> - <para>No Name <email>vode@hut.fi</email></para> - </listitem> - - <listitem> - <para>No Name <email>wlloyd@mpd.ca</email></para> - </listitem> - - <listitem> - <para>No Name <email>wlr@furball.wellsfargo.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>yamagata@nwgpc.kek.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>ziggy@ryan.org</email></para> - </listitem> - - <listitem> - <para>Nobuhiro Yasutomi <email>nobu@psrc.isac.co.jp</email></para> - </listitem> - - <listitem> - <para>Nobuyuki Koganemaru - <email>kogane@koganemaru.co.jp</email></para> - </listitem> - - <listitem> - <para>Norio Suzuki <email>nosuzuki@e-mail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Noritaka Ishizumi <email>graphite@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Noriyuki Soda <email>soda@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Oh Junseon <email>hollywar@mail.holywar.net</email></para> - </listitem> - - <listitem> - <para>Olaf Wagner <email>wagner@luthien.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Oleg Sharoiko <email>os@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Oleg V. Volkov <email>rover@lglobus.ru</email></para> - </listitem> - - <listitem> - <para>Oliver Breuninger <email>ob@seicom.NET</email></para> - </listitem> - - <listitem> - <para>Oliver Friedrichs <email>oliver@secnet.com</email></para> - </listitem> - - <listitem> - <para>Oliver Fromme - <email>oliver.fromme@heim3.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Oliver Laumann - <email>net@informatik.uni-bremen.de</email></para> - </listitem> - - <listitem> - <para>Oliver Oberdorf <email>oly@world.std.com</email></para> - </listitem> - - <listitem> - <para>Olof Johansson <email>offe@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Osokin Sergey aka oZZ <email>ozz@FreeBSD.org.ru</email></para> - </listitem> - - <listitem> - <para>Pace Willisson <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paco Rosich <email>rosich@modico.eleinf.uv.es</email></para> - </listitem> - - <listitem> - <para>Palle Girgensohn <email>girgen@partitur.se</email></para> - </listitem> - - <listitem> - <para>Parag Patel <email>parag@cgt.com</email></para> - </listitem> - - <listitem> - <para>Pascal Pederiva <email>pascal@zuo.dec.com</email></para> - </listitem> - - <listitem> - <para>Pasvorn Boonmark <email>boonmark@juniper.net</email></para> - </listitem> - - <listitem> - <para>Patrick Gardella <email>patrick@cre8tivegroup.com</email></para> - </listitem> - - <listitem> - <para>Patrick Hausen <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Antonov <email>apg@demos.su</email></para> - </listitem> - - <listitem> - <para>Paul F. Werkowski <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Fox <email>pgf@foxharp.boston.ma.us</email></para> - </listitem> - - <listitem> - <para>Paul Koch <email>koch@thehub.com.au</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg <email>pk@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Paul S. LaFollette, Jr. <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Saab <email>paul@mu.org</email></para> - </listitem> - - <listitem> - <para>Paul Sandys <email>myj@nyct.net</email></para> - </listitem> - - <listitem> - <para>Paul T. Root <email>proot@horton.iaces.com</email></para> - </listitem> - - <listitem> - <para>Paul Vixie <email>paul@vix.com</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes <email>paulo@isr.uc.pt</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes <email>pm@dee.uc.pt</email></para> - </listitem> - - <listitem> - <para>Pedro A M Vazquez <email>vazquez@IQM.Unicamp.BR</email></para> - </listitem> - - <listitem> - <para>Pedro Giffuni <email>giffunip@asme.org</email></para> - </listitem> - - <listitem> - <para>Pete Bentley <email>pete@demon.net</email></para> - </listitem> - - <listitem> - <para>Peter Childs <email>pjchilds@imforei.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Peter Cornelius <email>pc@inr.fzk.de</email></para> - </listitem> - - <listitem> - <para>Peter Haight <email>peterh@prognet.com</email></para> - </listitem> - - <listitem> - <para>Peter Jeremy <email>perer.jeremy@alcatel.com.au</email></para> - </listitem> - - <listitem> - <para>Peter M. Chen <email>pmchen@eecs.umich.edu</email></para> - </listitem> - - <listitem> - <para>Peter Much <email>peter@citylink.dinoex.sub.org</email></para> - </listitem> - - <listitem> - <para>Peter Olsson <email>unknown</email></para> - </listitem> - - <listitem> - <para>Peter Philipp <email>pjp@bsd-daemon.net</email></para> - </listitem> - - <listitem> - <para>Peter Stubbs <email>PETERS@staidan.qld.edu.au</email></para> - </listitem> - - <listitem> - <para>Phil Maker <email>pjm@cs.ntu.edu.au</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland - <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Phil Taylor <email>phil@zipmail.co.uk</email></para> - </listitem> - - <listitem> - <para>Philip Musumeci <email>philip@rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Pierre Y. Dampure <email>pierre.dampure@k2c.co.uk</email></para> - </listitem> - - <listitem> - <para>Pius Fischer <email>pius@ienet.com</email></para> - </listitem> - - <listitem> - <para>Pomegranate <email>daver@flag.blackened.net</email></para> - </listitem> - - <listitem> - <para>Powerdog Industries - <email>kevin.ruddy@powerdog.com</email></para> - </listitem> - - <listitem> - <para>R. Kym Horsell</para> - </listitem> - - <listitem> - <para>Rajesh Vaidheeswarran <email>rv@fore.com</email></para> - </listitem> - - <listitem> - <para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Randal S. Masutani <email>randal@comtest.com</email></para> - </listitem> - - <listitem> - <para>Randall Hopper <email>rhh@ct.picker.com</email></para> - </listitem> - - <listitem> - <para>Randall W. Dean <email>rwd@osf.org</email></para> - </listitem> - - <listitem> - <para>Randy Bush <email>rbush@bainbridge.verio.net</email></para> - </listitem> - - <listitem> - <para>Reinier Bezuidenhout - <email>rbezuide@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Remy Card <email>Remy.Card@masi.ibp.fr</email></para> - </listitem> - - <listitem> - <para>Ricardas Cepas <email>rch@richard.eu.org</email></para> - </listitem> - - <listitem> - <para>Riccardo Veraldi <email>veraldi@cs.unibo.it</email></para> - </listitem> - - <listitem> - <para>Richard Henderson <email>richard@atheist.tamu.edu</email></para> - </listitem> - - <listitem> - <para>Richard Hwang <email>rhwang@bigpanda.com</email></para> - </listitem> - - <listitem> - <para>Richard Kiss <email>richard@homemail.com</email></para> - </listitem> - - <listitem> - <para>Richard J Kuhns <email>rjk@watson.grauel.com</email></para> - </listitem> - - <listitem> - <para>Richard M. Neswold - <email>rneswold@drmemory.fnal.gov</email></para> - </listitem> - - <listitem> - <para>Richard Seaman, Jr. <email>dick@tar.com</email></para> - </listitem> - - <listitem> - <para>Richard Stallman <email>rms@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Richard Straka <email>straka@user1.inficad.com</email></para> - </listitem> - - <listitem> - <para>Richard Tobin <email>richard@cogsci.ed.ac.uk</email></para> - </listitem> - - <listitem> - <para>Richard Wackerbarth <email>rkw@Dataplex.NET</email></para> - </listitem> - - <listitem> - <para>Richard Winkel <email>rich@math.missouri.edu</email></para> - </listitem> - - <listitem> - <para>Richard Wiwatowski <email>rjwiwat@adelaide.on.net</email></para> - </listitem> - - <listitem> - <para>Rick Macklem <email>rick@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Rick Macklin <email>unknown</email></para> - </listitem> - - <listitem> - <para>Rob Austein <email>sra@epilogue.com</email></para> - </listitem> - - <listitem> - <para>Rob Mallory <email>rmallory@qualcomm.com</email></para> - </listitem> - - <listitem> - <para>Rob Snow <email>rsnow@txdirect.net</email></para> - </listitem> - - <listitem> - <para>Robert Crowe <email>bob@speakez.com</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Robert Eckardt - <email>roberte@MEP.Ruhr-Uni-Bochum.de</email></para> - </listitem> - - <listitem> - <para>Robert Sanders <email>rsanders@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Robert Sexton <email>robert@kudra.com</email></para> - </listitem> - - <listitem> - <para>Robert Shady <email>rls@id.net</email></para> - </listitem> - - <listitem> - <para>Robert Swindells <email>swindellsr@genrad.co.uk</email></para> - </listitem> - - <listitem> - <para>Robert Watson <email>robert@cyrus.watson.org</email></para> - </listitem> - - <listitem> - <para>Robert Withrow <email>witr@rwwa.com</email></para> - </listitem> - - <listitem> - <para>Robert Yoder <email>unknown</email></para> - </listitem> - - <listitem> - <para>Robin Carey - <email>robin@mailgate.dtc.rankxerox.co.uk</email></para> - </listitem> - - <listitem> - <para>Roger Hardiman <email>roger@cs.strath.ac.uk</email></para> - </listitem> - - <listitem> - <para>Roland Jesse <email>jesse@cs.uni-magdeburg.de</email></para> - </listitem> - - <listitem> - <para>Ron Bickers <email>rbickers@intercenter.net</email></para> - </listitem> - - <listitem> - <para>Ron Lenk <email>rlenk@widget.xmission.com</email></para> - </listitem> - - <listitem> - <para>Ronald Kuehn <email>kuehn@rz.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Rudolf Cejka <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ruslan Belkin <email>rus@home2.UA.net</email></para> - </listitem> - - <listitem> - <para>Ruslan Ermilov <email>ru@ucb.crimea.ua</email></para> - </listitem> - - <listitem> - <para>Ruslan Shevchenko <email>rssh@cam.grad.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Russell L. Carter <email>rcarter@pinyon.org</email></para> - </listitem> - - <listitem> - <para>Russell Vincent <email>rv@groa.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Ryan Younce <email>ryany@pobox.com</email></para> - </listitem> - - <listitem> - <para>Ryuichiro IMURA <email>imura@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>SANETO Takanori <email>sanewo@strg.sony.co.jp</email></para> - </listitem> - - <listitem> - <para>SAWADA Mizuki <email>miz@qb3.so-net.ne.jp</email></para> - </listitem> - - <listitem> - <para>SUGIMURA Takashi <email>sugimura@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>SURANYI Peter - <email>suranyip@jks.is.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>Sakai Hiroaki <email>sakai@miya.ee.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Sakari Jalovaara <email>sja@tekla.fi</email></para> - </listitem> - - <listitem> - <para>Sam Hartman <email>hartmans@mit.edu</email></para> - </listitem> - - <listitem> - <para>Samuel Lam <email>skl@ScalableNetwork.com</email></para> - </listitem> - - <listitem> - <para>Samuele Zannoli <email>zannoli@cs.unibo.it</email></para> - </listitem> - - <listitem> - <para>Sander Vesik <email>sander@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Sandro Sigala <email>ssigala@globalnet.it</email></para> - </listitem> - - <listitem> - <para>Sascha Blank <email>blank@fox.uni-trier.de</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Satoh Junichi <email>junichi@astec.co.jp</email></para> - </listitem> - - <listitem> - <para>Scot Elliott <email>scot@poptart.org</email></para> - </listitem> - - <listitem> - <para>Scot W. Hetzel <email>hetzels@westbend.net</email></para> - </listitem> - - <listitem> - <para>Scott A. Kenney <email>saken@rmta.ml.org</email></para> - </listitem> - - <listitem> - <para>Scott Blachowicz - <email>scott.blachowicz@seaslug.org</email></para> - </listitem> - - <listitem> - <para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Hazen Mueller <email>scott@zorch.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Scott Michel <email>scottm@cs.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Mitchel <email>scott@uk.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Sebastian Strollo <email>seb@erix.ericsson.se</email></para> - </listitem> - - <listitem> - <para>Serge A. Babkin <email>babkin@hq.icb.chel.su</email></para> - </listitem> - - <listitem> - <para>Serge V. Vakulenko <email>vak@zebub.msk.su</email></para> - </listitem> - - <listitem> - <para>Sergei Chechetkin - <email>csl@whale.sunbay.crimea.ua</email></para> - </listitem> - - <listitem> - <para>Sergei S. Laskavy <email>laskavy@pc759.cs.msu.su</email></para> - </listitem> - - <listitem> - <para>Sergey Gershtein <email>sg@mplik.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Kosyakov <email>ks@itp.ac.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Potapov <email>sp@alkor.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Shkonda <email>serg@bcs.zp.ua</email></para> - </listitem> - - <listitem> - <para>Sergey V.Dorokhov <email>svd@kbtelecom.nalnet.ru</email></para> - </listitem> - - <listitem> - <para>Sergio Lenzi <email>lenzi@bsi.com.br</email></para> - </listitem> - - <listitem> - <para>Shaun Courtney <email>shaun@emma.eng.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Shawn M. Carey <email>smcarey@mailbox.syr.edu</email></para> - </listitem> - - <listitem> - <para>Shigio Yamaguchi <email>shigio@tamacom.com</email></para> - </listitem> - - <listitem> - <para>Shinya Esu <email>esu@yk.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Shuichi Tanaka <email>stanaka@bb.mbn.or.jp</email></para> - </listitem> - - <listitem> - <para>Shunsuke Akiyama <email>akiyama@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Simon <email>simon@masi.ibp.fr</email></para> - </listitem> - - <listitem> - <para>Simon Burge <email>simonb@telstra.com.au</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email></para> - </listitem> - - <listitem> - <para>Simon Marlow <email>simonm@dcs.gla.ac.uk</email></para> - </listitem> - - <listitem> - <para>Simon Shapiro <email>shimon@simon-shapiro.org</email></para> - </listitem> - - <listitem> - <para>Sin'ichiro MIYATANI <email>siu@phaseone.co.jp</email></para> - </listitem> - - <listitem> - <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email></para> - </listitem> - - <listitem> - <para>Soochon Radee <email>slr@mitre.org</email></para> - </listitem> - - <listitem> - <para>Soren Dayton <email>csdayton@midway.uchicago.edu</email></para> - </listitem> - - <listitem> - <para>Soren Dossing <email>sauber@netcom.com</email></para> - </listitem> - - <listitem> - <para>Soren S. Jorvang <email>soren@dt.dk</email></para> - </listitem> - - <listitem> - <para>Stefan Bethke <email>stb@hanse.de</email></para> - </listitem> - - <listitem> - <para>Stefan Eggers <email>seggers@semyam.dinoco.de</email></para> - </listitem> - - <listitem> - <para>Stefan Moeding <email>s.moeding@ndh.net</email></para> - </listitem> - - <listitem> - <para>Stefan Petri <email>unknown</email></para> - </listitem> - - <listitem> - <para>Stefan `Sec` Zehl <email>sec@42.org</email></para> - </listitem> - - <listitem> - <para>Steinar Haug <email>sthaug@nethelp.no</email></para> - </listitem> - - <listitem> - <para>Stephane E. Potvin <email>sepotvin@videotron.ca</email></para> - </listitem> - - <listitem> - <para>Stephane Legrand <email>stephane@lituus.fr</email></para> - </listitem> - - <listitem> - <para>Stephen Clawson - <email>sclawson@marker.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Stephen F. Combs <email>combssf@salem.ge.com</email></para> - </listitem> - - <listitem> - <para>Stephen Farrell <email>stephen@farrell.org</email></para> - </listitem> - - <listitem> - <para>Stephen Hocking <email>sysseh@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Stephen J. Roznowski <email>sjr@home.net</email></para> - </listitem> - - <listitem> - <para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Stephen Melvin <email>melvin@zytek.com</email></para> - </listitem> - - <listitem> - <para>Steve Bauer <email>sbauer@rock.sdsmt.edu</email></para> - </listitem> - - <listitem> - <para>Steve Coltrin <email>spcoltri@io.com</email></para> - </listitem> - - <listitem> - <para>Steve Deering <email>unknown</email></para> - </listitem> - - <listitem> - <para>Steve Gerakines <email>steve2@genesis.tiac.net</email></para> - </listitem> - - <listitem> - <para>Steve Gericke <email>steveg@comtrol.com</email></para> - </listitem> - - <listitem> - <para>Steve Piette <email>steve@simon.chi.il.US</email></para> - </listitem> - - <listitem> - <para>Steve Schwarz <email>schwarz@alpharel.com</email></para> - </listitem> - - <listitem> - <para>Steven G. Kargl - <email>kargl@troutmask.apl.washington.edu</email></para> - </listitem> - - <listitem> - <para>Steven H. Samorodin <email>samorodi@NUXI.com</email></para> - </listitem> - - <listitem> - <para>Steven McCanne <email>mccanne@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Steven Plite <email>splite@purdue.edu</email></para> - </listitem> - - <listitem> - <para>Steven Wallace <email>unknown</email></para> - </listitem> - - <listitem> - <para>Stuart Henderson - <email>stuart@internationalschool.co.uk</email></para> - </listitem> - - <listitem> - <para>Sue Blake <email>sue@welearn.com.au</email></para> - </listitem> - - <listitem> - <para>Sugimoto Sadahiro <email>ixtl@komaba.utmc.or.jp</email></para> - </listitem> - - <listitem> - <para>Sugiura Shiro <email>ssugiura@duo.co.jp</email></para> - </listitem> - - <listitem> - <para>Sujal Patel <email>smpatel@wam.umd.edu</email></para> - </listitem> - - <listitem> - <para>Sune Stjerneby <email>stjerneby@usa.net</email></para> - </listitem> - - <listitem> - <para>Suzuki Yoshiaki - <email>zensyo@ann.tama.kawasaki.jp</email></para> - </listitem> - - <listitem> - <para>Tadashi Kumano <email>kumano@strl.nhk.or.jp</email></para> - </listitem> - - <listitem> - <para>Taguchi Takeshi <email>taguchi@tohoku.iij.ad.jp</email></para> - </listitem> - - <listitem> - <para>Takahiro Yugawa <email>yugawa@orleans.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Takanori Watanabe - <email>takawata@shidahara1.planet.sci.kobe-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takashi Mega <email>mega@minz.org</email></para> - </listitem> - - <listitem> - <para>Takashi Uozu <email>j1594016@ed.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takayuki Ariga <email>a00821@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeru NAIKI <email>naiki@bfd.es.hokudai.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi Amaike <email>amaike@iri.co.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi MUTOH <email>mutoh@info.nara-k.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi Ohashi - <email>ohashi@mickey.ai.kyutech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi WATANABE - <email>watanabe@crayon.earth.s.kobe-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takuya SHIOZAKI - <email>tshiozak@makino.ise.chuo-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tatoku Ogaito <email>tacha@tera.fukui-med.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tatsumi HOSOKAWA <email>hosokawa@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Ted Buswell <email>tbuswell@mediaone.net</email></para> - </listitem> - - <listitem> - <para>Ted Faber <email>faber@isi.edu</email></para> - </listitem> - - <listitem> - <para>Ted Lemon <email>mellon@isc.org</email></para> - </listitem> - - <listitem> - <para>Terry Lambert <email>terry@lambert.org</email></para> - </listitem> - - <listitem> - <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tetsuya Furukawa <email>tetsuya@secom-sis.co.jp</email></para> - </listitem> - - <listitem> - <para>Theo de Raadt <email>deraadt@OpenBSD.org</email></para> - </listitem> - - <listitem> - <para>Thomas <email>thomas@mathematik.uni-Bremen.de</email></para> - </listitem> - - <listitem> - <para>Thomas D. Dean <email>tomdean@ix.netcom.com</email></para> - </listitem> - - <listitem> - <para>Thomas David Rivers <email>rivers@dignus.com</email></para> - </listitem> - - <listitem> - <para>Thomas G. McWilliams <email>tgm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Thomas Gellekum - <email>thomas@ghpc8.ihf.rwth-aachen.de</email></para> - </listitem> - - <listitem> - <para>Thomas Graichen - <email>graichen@omega.physik.fu-berlin.de</email></para> - </listitem> - - <listitem> - <para>Thomas König - <email>Thomas.Koenig@ciw.uni-karlsruhe.de</email></para> - </listitem> - - <listitem> - <para>Thomas Ptacek <email>unknown</email></para> - </listitem> - - <listitem> - <para>Thomas A. Stephens <email>tas@stephens.org</email></para> - </listitem> - - <listitem> - <para>Thomas Stromberg <email>tstrombe@rtci.com</email></para> - </listitem> - - <listitem> - <para>Thomas Valentino Crimi - <email>tcrimi+@andrew.cmu.edu</email></para> - </listitem> - - <listitem> - <para>Thomas Wintergerst <email>thomas@lemur.nord.de</email></para> - </listitem> - - <listitem> - <para>Þórður Ívarsson - <email>totii@est.is</email></para> - </listitem> - - <listitem> - <para>Tim Kientzle <email>kientzle@netcom.com</email></para> - </listitem> - - <listitem> - <para>Tim Singletary - <email>tsingle@sunland.gsfc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Tim Wilkinson <email>tim@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Timo J. Rinne <email>tri@iki.fi</email></para> - </listitem> - - <listitem> - <para>Todd Miller <email>millert@openbsd.org</email></para> - </listitem> - - <listitem> - <para>Tom <email>root@majestix.cmr.no</email></para> - </listitem> - - <listitem> - <para>Tom <email>tom@sdf.com</email></para> - </listitem> - - <listitem> - <para>Tom Gray - DCA <email>dcasba@rain.org</email></para> - </listitem> - - <listitem> - <para>Tom Jobbins <email>tom@tom.tj</email></para> - </listitem> - - <listitem> - <para>Tom Pusateri <email>pusateri@juniper.net</email></para> - </listitem> - - <listitem> - <para>Tom Rush <email>tarush@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Tom Samplonius <email>tom@misery.sdf.com</email></para> - </listitem> - - <listitem> - <para>Tomohiko Kurahashi - <email>kura@melchior.q.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tony Kimball <email>alk@Think.COM</email></para> - </listitem> - - <listitem> - <para>Tony Li <email>tli@jnx.com</email></para> - </listitem> - - <listitem> - <para>Tony Lynn <email>wing@cc.nsysu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Tony Maher <email>tonym@angis.org.au</email></para> - </listitem> - - <listitem> - <para>Torbjorn Granlund <email>tege@matematik.su.se</email></para> - </listitem> - - <listitem> - <para>Toshihiko ARAI <email>toshi@tenchi.ne.jp</email></para> - </listitem> - - <listitem> - <para>Toshihiko SHIMOKAWA <email>toshi@tea.forus.or.jp</email></para> - </listitem> - - <listitem> - <para>Toshihiro Kanda <email>candy@kgc.co.jp</email></para> - </listitem> - - <listitem> - <para>Toshiomi Moriki - <email>Toshiomi.Moriki@ma1.seikyou.ne.jp</email></para> - </listitem> - - <listitem> - <para>Trefor S. <email>trefor@flevel.co.uk</email></para> - </listitem> - - <listitem> - <para>Trevor Blackwell <email>tlb@viaweb.com</email></para> - </listitem> - - <listitem> - <para>URATA Shuichiro <email>s-urata@nmit.tmg.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>Udo Schweigert <email>ust@cert.siemens.de</email></para> - </listitem> - - <listitem> - <para>Ugo Paternostro <email>paterno@dsi.unifi.it</email></para> - </listitem> - - <listitem> - <para>Ulf Kieber <email>kieber@sax.de</email></para> - </listitem> - - <listitem> - <para>Ulli Linzen <email>ulli@perceval.camelot.de</email></para> - </listitem> - - <listitem> - <para>Ustimenko Semen <email>semen@iclub.nsu.ru</email></para> - </listitem> - - <listitem> - <para>Uwe Arndt <email>arndt@mailhost.uni-koblenz.de</email></para> - </listitem> - - <listitem> - <para>Vadim Chekan <email>vadim@gc.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Vadim Kolontsov <email>vadim@tversu.ac.ru</email></para> - </listitem> - - <listitem> - <para>Vadim Mikhailov <email>mvp@braz.ru</email></para> - </listitem> - - <listitem> - <para>Van Jacobson <email>van@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Vasily V. Grechishnikov - <email>bazilio@ns1.ied-vorstu.ac.ru</email></para> - </listitem> - - <listitem> - <para>Vasim Valejev <email>vasim@uddias.diaspro.com</email></para> - </listitem> - - <listitem> - <para>Vernon J. Schryver <email>vjs@mica.denver.sgi.com</email></para> - </listitem> - - <listitem> - <para>Vic Abell <email>abe@cc.purdue.edu</email></para> - </listitem> - - <listitem> - <para>Ville Eerola <email>ve@sci.fi</email></para> - </listitem> - - <listitem> - <para>Vincent Poy <email>vince@venus.gaianet.net</email></para> - </listitem> - - <listitem> - <para>Vincenzo Capuano - <email>VCAPUANO@vmprofs.esoc.esa.de</email></para> - </listitem> - - <listitem> - <para>Virgil Champlin <email>champlin@pa.dec.com</email></para> - </listitem> - - <listitem> - <para>Vladimir A. Jakovenko - <email>vovik@ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Vladimir Kushnir <email>kushn@mail.kar.net</email></para> - </listitem> - - <listitem> - <para>Vsevolod Lobko <email>seva@alex-ua.com</email></para> - </listitem> - - <listitem> - <para>W. Gerald Hicks <email>wghicks@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>W. Richard Stevens <email>rstevens@noao.edu</email></para> - </listitem> - - <listitem> - <para>Walt Howard <email>howard@ee.utah.edu</email></para> - </listitem> - - <listitem> - <para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wayne Scott <email>wscott@ichips.intel.com</email></para> - </listitem> - - <listitem> - <para>Werner Griessl - <email>werner@btp1da.phy.uni-bayreuth.de</email></para> - </listitem> - - <listitem> - <para>Wes Santee <email>wsantee@wsantee.oz.net</email></para> - </listitem> - - <listitem> - <para>Wietse Venema <email>wietse@wzv.win.tue.nl</email></para> - </listitem> - - <listitem> - <para>Wilfredo Sanchez <email>wsanchez@apple.com</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>Wilko Bulte <email>wilko@yedi.iaf.nl</email></para> - </listitem> - - <listitem> - <para>Will Andrews <email>andrews@technologist.com</email></para> - </listitem> - - <listitem> - <para>Willem Jan Withagen <email>wjw@surf.IAE.nl</email></para> - </listitem> - - <listitem> - <para>William Jolitz <email>withheld</email></para> - </listitem> - - <listitem> - <para>William Liao <email>william@tale.net</email></para> - </listitem> - - <listitem> - <para>Wojtek Pilorz - <email>wpilorz@celebris.bdk.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Wolfgang Helbig <email>helbig@ba-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier <email>wolf@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Wu Ching-hong <email>woju@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>Yarema <email>yds@ingress.com</email></para> - </listitem> - - <listitem> - <para>Yaroslav Terletsky <email>ts@polynet.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Yasuhito FUTATSUKI <email>futatuki@fureai.or.jp</email></para> - </listitem> - - <listitem> - <para>Yasuhiro Fukama <email>yasuf@big.or.jp</email></para> - </listitem> - - <listitem> - <para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Ying-Chieh Liao <email>ijliao@csie.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yixin Jin <email>yjin@rain.cs.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yoshihiko OHTA <email>yohta@bres.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yoshihisa NAKAGAWA - <email>y-nakaga@ccs.mt.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>Yoshikazu Goto <email>gotoh@ae.anritsu.co.jp</email></para> - </listitem> - - <listitem> - <para>Yoshimasa Ohnishi - <email>ohnishi@isc.kyutech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yoshishige Arai <email>ryo2@on.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yuichi MATSUTAKA <email>matutaka@osa.att.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yujiro MIYATA - <email>miyata@bioele.nuee.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yukihiro Nakai <email>nacai@iname.com</email></para> - </listitem> - - <listitem> - <para>Yusuke Nawano <email>azuki@azkey.org</email></para> - </listitem> - - <listitem> - <para>Yuu Yashiki <email>s974123@cc.matsuyama-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para> - </listitem> - - <listitem> - <para>Yves Fonk <email>yves@cpcoup5.tn.tudelft.nl</email></para> - </listitem> - - <listitem> - <para>Yves Fonk <email>yves@dutncp8.tn.tudelft.nl</email></para> - </listitem> - - <listitem> - <para>Zach Heilig <email>zach@gaffaneys.com</email></para> - </listitem> - - <listitem> - <para>Zahemszhky Gabor <email>zgabor@code.hu</email></para> - </listitem> - - <listitem> - <para>Zhong Ming-Xun <email>zmx@mail.CDPA.nsysu.edu.tw</email></para> - </listitem> - - <listitem> - <para>arci <email>vega@sophia.inria.fr</email></para> - </listitem> - - <listitem> - <para>der Mouse <email>mouse@Collatz.McRCIM.McGill.EDU</email></para> - </listitem> - - <listitem> - <para>frf <email>frf@xocolatl.com</email></para> - </listitem> - - <listitem> - <para>Ege Rekk <email>aagero@aage.priv.no</email></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>386BSD Patch Kit Patch Contributors</title> - - <para>(in alphabetical order by first name):</para> - - <itemizedlist> - <listitem> - <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Hall <email>adrian@ibmpcug.co.uk</email></para> - </listitem> - - <listitem> - <para>Andrey A. Chernov <email>ache@astral.msk.su</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew Moore <email>alm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Andy Valencia <email>ajv@csd.mot.com</email> - <email>jtk@netcom.com</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Bakul Shah <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Lustig <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Bob Wilcox <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Branko Lankester</para> - </listitem> - - <listitem> - <para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Chris G. Demetriou - <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko - <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Rivers <email>rivers@ponds.uucp</email></para> - </listitem> - - <listitem> - <para>David Dawes <email>dawes@physics.su.OZ.AU</email></para> - </listitem> - - <listitem> - <para>David Greenman <email>dg@Root.COM</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Felix Gaehtgens - <email>felix@escape.vsse.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Frank Maclachlan <email>fpm@crash.cts.com</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Guido van Rooij <email>guido@gvr.org</email></para> - </listitem> - - <listitem> - <para>Guy Harris <email>guy@auspex.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes - <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl <email>hpeyerl@novatel.cuc.ab.ca</email></para> - </listitem> - - <listitem> - <para>Holger Veit <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Ishii Masahiro, R. Kym Horsell</para> - </listitem> - - <listitem> - <para>J.T. Conklin <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>James Clark <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James W. Dolter</para> - </listitem> - - <listitem> - <para>James da Silva <email>jds@cs.umd.edu</email> et al</para> - </listitem> - - <listitem> - <para>Jay Fenlason <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jörg Lohse - <email>lohse@tech7.informatik.uni-hamburg.de</email></para> - </listitem> - - <listitem> - <para>Jörg Wunsch - <email>joerg_wunsch@uriah.heep.sax.de</email></para> - </listitem> - - <listitem> - <para>John Dyson</para> - </listitem> - - <listitem> - <para>John Woods <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Jordan K. Hubbard <email>jkh@whisker.hubbard.ie</email></para> - </listitem> - - <listitem> - <para>Julian Elischer <email>julian@dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Julian Stacey <email>jhs@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer <email>karl@NeoSoft.com</email> - <email>karl@one.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Keith Bostic <email>bostic@toe.CS.Berkeley.EDU</email></para> - </listitem> - - <listitem> - <para>Ken Hughes</para> - </listitem> - - <listitem> - <para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey <email>kml%rokkaku.UUCP@mathcs.emory.edu</email> - <email>kml@mosquito.cis.ufl.edu</email></para> - </listitem> - - <listitem> - <para>Marc Frajola <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email> - <email>tinguely@hookie.cs.ndsu.NoDak.edu</email></para> - </listitem> - - <listitem> - <para>Martin Renters <email>martin@tdc.on.ca</email></para> - </listitem> - - <listitem> - <para>Michael Clay <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Nate Williams <email>nate@bsd.coe.montana.edu</email></para> - </listitem> - - <listitem> - <para>Nick Handel <email>nhandel@NeoSoft.com</email> - <email>nick@madhouse.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Pace Willisson <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg <email>pk@cs.few.eur.nl</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Peter da Silva <email>peter@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland - <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Poul-Henning Kamp<email>phk@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Rick Macklem <email>root@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Rodney W. Grimes <email>rgrimes@cdrom.com</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Sean Eric Fagan <email>sef@kithrup.com</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email> - <email>sjg@zen.void.oz.au</email></para> - </listitem> - - <listitem> - <para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Terry Lambert <email>terry@icarus.weber.edu</email></para> - </listitem> - - <listitem> - <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tor Egge <email>Tor.Egge@idi.ntnu.no</email></para> - </listitem> - - <listitem> - <para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>William Jolitz <email>withheld</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier <email>wolf@dentaro.GUN.de</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para> - </listitem> - </itemizedlist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/cutting-edge/chapter.sgml b/en/handbook/cutting-edge/chapter.sgml deleted file mode 100644 index 0889a7e540..0000000000 --- a/en/handbook/cutting-edge/chapter.sgml +++ /dev/null @@ -1,2482 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.23 1999-08-02 11:29:15 asami Exp $ ---> - -<chapter id="cutting-edge"> - <title>The Cutting Edge: FreeBSD-current and FreeBSD-stable</title> - - <para>FreeBSD is under constant development between releases. For people - who want to be on the cutting edge, there are several easy mechanisms for - keeping your system in sync with the latest developments. Be warned: the - cutting edge is not for everyone! This chapter will help you decide if you - want to track the development system, or stick with one of the released - versions.</para> - - <sect1 id="current"> - <title>Staying Current with FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <sect2> - <title>What is FreeBSD-current?</title> - - <para>FreeBSD-current is, quite literally, nothing more than a daily - snapshot of the working sources for FreeBSD. These include work in - progress, experimental changes and transitional mechanisms that may or - may not be present in the next official release of the software. - While many of us compile almost daily from FreeBSD-current sources, - there are periods of time when the sources are literally - un-compilable. These problems are generally resolved as expeditiously - as possible, but whether or not FreeBSD-current sources bring disaster - or greatly desired functionality can literally be a matter of which - part of any given 24 hour period you grabbed them in!</para> - </sect2> - - <sect2> - <title>Who needs FreeBSD-current?</title> - - <para>FreeBSD-current is made generally available for 3 primary interest - groups:</para> - - <orderedlist> - <listitem> - <para>Members of the FreeBSD group who are actively working on some - part of the source tree and for whom keeping “current” - is an absolute requirement.</para> - </listitem> - - <listitem> - <para>Members of the FreeBSD group who are active testers, willing - to spend time working through problems in order to ensure that - FreeBSD-current remains as sane as possible. These are also people - who wish to make topical suggestions on changes and the general - direction of FreeBSD.</para> - </listitem> - - <listitem> - <para>Peripheral members of the FreeBSD (or some other) group who - merely wish to keep an eye on things and use the current sources - for reference purposes (e.g. for <emphasis>reading</emphasis>, not - running). These people also make the occasional comment or - contribute code.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>What is FreeBSD-current <emphasis>not</emphasis>?</title> - - <orderedlist> - <listitem> - <para>A fast-track to getting pre-release bits because you heard - there is some cool new feature in there and you want to be the - first on your block to have it.</para> - </listitem> - - <listitem> - <para>A quick way of getting bug fixes.</para> - </listitem> - - <listitem> - <para>In any way “officially supported” by us. We do - our best to help people genuinely in one of the 3 - “legitimate” FreeBSD-current categories, but we simply - <emphasis>do not have the time</emphasis> to provide tech support - for it. This is not because we are mean and nasty people who do - not like helping people out (we would not even be doing FreeBSD if - we were), it is literally because we cannot answer 400 messages a - day <emphasis>and</emphasis> actually work on FreeBSD! I am sure - that, if given the choice between having us answer lots of - questions or continuing to improve FreeBSD, most of you would vote - for us improving it.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Using FreeBSD-current</title> - - <orderedlist> - <listitem> - <para>Join the &a.current; and the &a.cvsall; . This is not just a - good idea, it is <emphasis>essential</emphasis>. If you are not - on the <emphasis>FreeBSD-current</emphasis> mailing list, you will - not see the comments that people are making about the current - state of the system and thus will probably end up stumbling over a - lot of problems that others have already found and solved. Even - more importantly, you will miss out on important bulletins which - may be critical to your system's continued health.</para> - - <para>The <email>cvs-all</email> mailing list will allow you to see - the commit log entry for each change as it is made along with any - pertinent information on possible side-effects.</para> - - <para>To join these lists, send mail to - &a.majordomo; and specify: - - <programlisting> -subscribe freebsd-current -subscribe cvs-all</programlisting> - - in the body of your message. Optionally, you can also say - <literal>help</literal> and Majordomo will send you full help on - how to subscribe and unsubscribe to the various other mailing - lists we support.</para> - </listitem> - - <listitem> - <para>Grab the sources from <hostid - role="fqdn">ftp.FreeBSD.org</hostid>. You can do this in three - ways:</para> - - <orderedlist> - <listitem> - <para>Use the <application><link - linkend="ctm">CTM</link></application> facility. Unless - you have a good TCP/IP connection at a flat rate, this is - the way to do it.</para> - </listitem> - - <listitem> - <para>Use the <link linkend="cvsup">cvsup</link> program with - <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/standard-supfile">this - supfile</ulink>. This is the second most recommended - method, since it allows you to grab the entire collection - once and then only what has changed from then on. Many people - run cvsup from cron and keep their sources up-to-date - automatically. For a fairly easy interface to this, simply - type:</para> - - <blockquote><screen>&prompt.root; <userinput>pkg_add -f \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></screen></blockquote> - </listitem> - - <listitem> - <para>Use <command>ftp</command>. The source tree for - FreeBSD-current is always “exported” on: <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current</ulink>. - We also use <command>wu-ftpd</command> which allows - compressed/tar'd grabbing of whole trees. e.g. you - see:</para> - - <screen>usr.bin/lex</screen> - - <para>You can do: - - <screen><prompt>ftp></prompt> <userinput>cd usr.bin</userinput> -<prompt>ftp></prompt> <userinput>get lex.tar.Z</userinput></screen> - - and it will get the whole directory for you as a compressed - tar file.</para> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>Essentially, if you need rapid on-demand access to the source - and communications bandwidth is not a consideration, use - <command>cvsup</command> or <command>ftp</command>. Otherwise, - use <application>CTM</application>.</para> - - <para>If you are grabbing the sources to run, and not just look at, - then grab <emphasis>all</emphasis> of current, not just selected - portions. The reason for this is that various parts of the source - depend on updates elsewhere, and trying to compile just a subset - is almost guaranteed to get you into trouble.</para> - - <para>Before compiling current, read the Makefile in - <filename>/usr/src</filename> carefully. You should at least run - a <link linkend="makeworld">make world</link> the first time - through as part of the upgrading process. Reading the &a.current; - will keep you up-to-date on other bootstrapping procedures that - sometimes become necessary as we move towards the next - release.</para> - </listitem> - - <listitem> - <para>Be active! If you are running FreeBSD-current, we want to - know what you have to say about it, especially if you have - suggestions for enhancements or bug fixes. Suggestions with - accompanying code are received most enthusiastically!</para> - </listitem> - </orderedlist> - </sect2> - </sect1> - - <sect1 id="stable"> - <title>Staying Stable with FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <sect2> - <title>What is FreeBSD-stable?</title> - - <para>FreeBSD-stable is our development branch for a more low-key and - conservative set of changes intended for our next mainstream release. - Changes of an experimental or untested nature do not go into this - branch (see <link linkend="current">FreeBSD-current</link>).</para> - </sect2> - - <sect2> - <title>Who needs FreeBSD-stable?</title> - - <para>If you are a commercial user or someone who puts maximum stability - of their FreeBSD system before all other concerns, you should consider - tracking <emphasis>stable</emphasis>. This is especially true if you - have installed the most recent release (<ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/&rel.current;-RELEASE">&rel.current;-RELEASE</ulink> - at the time of this writing) since the <emphasis>stable</emphasis> - branch is effectively a bug-fix stream relative to the previous - release.</para> - - <warning> - <para>The <emphasis>stable</emphasis> tree endeavors, above all, to be - fully compilable and stable at all times, but we do occasionally - make mistakes (these are still active sources with - quickly-transmitted updates, after all). We also do our best to - thoroughly test fixes in <emphasis>current</emphasis> before - bringing them into <emphasis>stable</emphasis>, but sometimes our - tests fail to catch every case. If something breaks for you in - <emphasis>stable</emphasis>, please let us know - <emphasis>immediately!</emphasis> (see next section).</para> - </warning> - </sect2> - - <sect2> - <title>Using FreeBSD-stable</title> - - <orderedlist> - - <listitem> - <para>Join the &a.stable;. This will keep you informed of - build-dependencies that may appear in <emphasis>stable</emphasis> - or any other issues requiring special attention. Developers will - also make announcements in this mailing list when they are - contemplating some controversial fix or update, giving the users a - chance to respond if they have any issues to raise concerning the - proposed change.</para> - - <para>The <email>cvs-all</email> mailing list will allow you to see - the commit log entry for each change as it is made along with any - pertinent information on possible side-effects.</para> - - <para>To join these lists, send mail to &a.majordomo; and specify: - - <programlisting> -subscribe freebsd-stable -subscribe cvs-all</programlisting> - - in the body of your message. Optionally, you can also say - <literal>help</literal> and Majordomo will send you full help on - how to subscribe and unsubscribe to the various other mailing - lists we support.</para> - </listitem> - - <listitem> - <para>If you are installing a new system and want it to be as stable - as possible, you can simply grab the latest dated branch snapshot - from <ulink - url="ftp://releng3.FreeBSD.org/pub/FreeBSD/">ftp://releng3.FreeBSD.org/pub/FreeBSD/</ulink> - and install it like any other release.</para> - - <para>If you are already running a previous release of 2.2 and wish - to upgrade via sources then you can easily do so from <hostid - role="fqdn">ftp.FreeBSD.org</hostid>. This can be done in one - of three ways:</para> - - <orderedlist> - <listitem> - <para>Use the <application><link - linkend="ctm">CTM</link></application> facility. Unless - you have a good TCP/IP connection at a flat rate, this is - the way to do it.</para> - </listitem> - - <listitem> - <para>Use the <link linkend="cvsup">cvsup</link> program with - <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this - supfile</ulink>. This is the second most recommended - method, since it allows you to grab the entire collection - once and then only what has changed from then on. Many people - run cvsup from cron to keep their sources up-to-date - automatically. For a fairly easy interface to this, simply - type;</para> - -<blockquote><screen>&prompt.root; <userinput>pkg_add -f \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></screen></blockquote> - </listitem> - - <listitem> - <para>Use <command>ftp</command>. The source tree for - FreeBSD-stable is always “exported” on: <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable</ulink></para> - - <para>We also use <command>wu-ftpd</command> which allows - compressed/tar'd grabbing of whole trees. e.g. you - see:</para> - - <screen>usr.bin/lex</screen> - - <para>You can do: - - <screen><prompt>ftp></prompt> <userinput>cd usr.bin</userinput> -<prompt>ftp></prompt> <userinput>get lex.tar.Z</userinput></screen> - - and it will get the whole directory for you as a compressed - tar file.</para> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>Essentially, if you need rapid on-demand access to the source - and communications bandwidth is not a consideration, use - <command>cvsup</command> or <command>ftp</command>. Otherwise, - use <application>CTM</application>.</para> - </listitem> - - <listitem> - <para>Before compiling stable, read the Makefile in - <filename>/usr/src</filename> carefully. You should at least run - a <link linkend="makeworld">make world</link> the first time - through as part of the upgrading process. Reading the &a.stable; - will keep you up-to-date on other bootstrapping procedures that - sometimes become necessary as we move towards the next - release.</para> - </listitem> - </orderedlist> - </sect2> - </sect1> - - <sect1 id="synching"> - <title>Synchronizing Source Trees over the Internet</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <para>There are various ways of using an Internet (or email) connection to - stay up-to-date with any given area of the FreeBSD project sources, or - all areas, depending on what interests you. The primary services we - offer are <link linkend="anoncvs">Anonymous CVS</link>, <link - linkend="cvsup">CVSup</link>, and <link - linkend="ctm">CTM</link>.</para> - - <para><application>Anonymous CVS</application> and - <application>CVSup</application> use the <emphasis>pull</emphasis> model - of updating sources. In the case of <application>CVSup</application> - the user (or a cron script) invokes the <command>cvsup</command> - program, and it interacts with a <command>cvsupd</command> server - somewhere to bring your files up to date. The updates you receive are - up-to-the-minute and you get them when, and only when, you want them. - You can easily restrict your updates to the specific files or - directories that are of interest to you. Updates are generated on the - fly by the server, according to what you have and what you want to have. - <application>Anonymous CVS</application> is quite a bit more simplistic - than CVSup in that it's just an extension to - <application>CVS</application> which allows it to pull changes directly - from a remote CVS repository. <application>CVSup</application> can do - this far more efficiently, but <application>Anonymous CVS</application> - is easier to use.</para> - - <para><application>CTM</application>, on the other hand, does not - interactively compare the sources you have with those on the master - archive or otherwise pull them across.. Instead, a script which - identifies changes in files since its previous run is executed several - times a day on the master CTM machine, any detected changes being - compressed, stamped with a sequence-number and encoded for transmission - over email (in printable ASCII only). Once received, these “CTM - deltas” can then be handed to the &man.ctm.rmail.1; utility which - will automatically decode, - verify and apply the changes to the user's copy of the sources. This - process is far more efficient than <application>CVSup</application>, and - places less strain on our server resources since it is a - <emphasis>push</emphasis> rather than a <emphasis>pull</emphasis> - model.</para> - - <para>There are other trade-offs, of course. If you inadvertently wipe - out portions of your archive, <application>CVSup</application> will - detect and rebuild the damaged portions for you. - <application>CTM</application> won't do this, and if you wipe some - portion of your source tree out (and don't have it backed up) then you - will have to start from scratch (from the most recent CVS “base - delta”) and rebuild it all with CTM or, with anoncvs, simply - delete the bad bits and resync.</para> - - <para>For more information on <application>Anonymous CVS</application>, - <application>CTM</application>, and <application>CVSup</application>, - please see one of the following sections:</para> - - <sect2 id="anoncvs"> - <title>Anonymous CVS</title> - - <para><emphasis>Contributed by &a.jkh;</emphasis></para> - - <sect3> - <title><anchor id="anoncvs-intro">Introduction</title> - - <para>Anonymous CVS (or, as it is otherwise known, - <emphasis>anoncvs</emphasis>) is a feature provided by the CVS - utilities bundled with FreeBSD for synchronizing with a remote CVS - repository. Among other things, it allows users of FreeBSD to - perform, with no special privileges, read-only CVS operations - against one of the FreeBSD project's official anoncvs servers. To - use it, one simply sets the <envar>CVSROOT</envar> environment - variable to point at the appropriate anoncvs server and then uses - the &man.cvs.1; command to access it like any local - repository.</para> - - <para>While it can also be said that the <link - linkend="cvsup">CVSup</link> and <emphasis>anoncvs</emphasis> - services both perform essentially the same function, there are - various trade-offs which can influence the user's choice of - synchronization methods. In a nutshell, - <application>CVSup</application> is much more efficient in its usage - of network resources and is by far the most technically - sophisticated of the two, but at a price. To use - <application>CVSup</application>, a special client must first be - installed and configured before any bits can be grabbed, and then - only in the fairly large chunks which - <application>CVSup</application> calls - <emphasis>collections</emphasis>.</para> - - <para><application>Anoncvs</application>, by contrast, can be used to - examine anything from an individual file to a specific program (like - <command>ls</command> or <command>grep</command>) by referencing the - CVS module name. Of course, <application>anoncvs</application> is - also only good for read-only operations on the CVS repository, so if - it's your intention to support local development in one repository - shared with the FreeBSD project bits then - <application>CVSup</application> is really your only option.</para> - </sect3> - - <sect3> - <title><anchor id="anoncvs-usage">Using Anonymous CVS</title> - - <para>Configuring &man.cvs.1; to use an Anonymous CVS repository is a - simple matter of setting the <envar>CVSROOT</envar> environment - variable to point to one of the FreeBSD project's - <emphasis>anoncvs</emphasis> servers. At the time of this writing, - the following servers are available:</para> - - <itemizedlist> - <listitem> - <para><emphasis>USA</emphasis>: - anoncvs@anoncvs.FreeBSD.org:/cvs</para> - </listitem> - </itemizedlist> - - <para>Since CVS allows one to “check out” virtually any - version of the FreeBSD sources that ever existed (or, in some cases, - will exist <!-- smiley -->:), you need to be familiar with the - revision (<option>-r</option>) flag to &man.cvs.1; and what some of - the permissible values for it in the FreeBSD Project repository - are.</para> - - <para>There are two kinds of tags, revision tags and branch tags. A - revision tag refers to a specific revision. Its meaning stays the - same from day to day. A branch tag, on the other hand, refers to - the latest revision on a given line of development, at any given - time. Because a branch tag does not refer to a specific revision, - it may mean something different tomorrow than it means today.</para> - - <para>Here are the branch tags that users might be interested - in:</para> - - <variablelist> - <varlistentry> - <term>HEAD</term> - - <listitem> - <para>Symbolic name for the main line, or FreeBSD-current. Also - the default when no revision is specified.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3</term> - - <listitem> - <para>The line of development for FreeBSD-3.x, also known as - FreeBSD-stable. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2</term> - - <listitem> - <para>The line of development for FreeBSD-2.2.x, also known as - 2.2-stable. This branch is mostly obsolete. Not valid for - the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_0</term> - - <listitem> - <para>The line of development for FreeBSD-2.1.x - this branch is - largely obsolete. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Here are the revision tags that users might be interested - in:</para> - - <variablelist> - <varlistentry> - - <term>RELENG_3_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.2. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - - <term>RELENG_3_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.1. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3_0_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.0. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_8_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.8. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.7. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.6. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.5. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_2_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.2. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.1. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.0. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.7. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_6_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.6.1. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.6. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.5. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.0. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>When you specify a branch tag, you normally receive the latest - versions of the files on that line of development. If you wish to - receive some past version, you can do so by specifying a date with - the <option>-D date</option> flag. See the &man.cvs.1; man page - for more details.</para> - </sect3> - - <sect3> - <title>Examples</title> - - <para>While it really is recommended that you read the manual page for - &man.cvs.1; thoroughly before doing anything, here are some - quick examples which essentially show how to use Anonymous - CVS:</para> - - <example> - <title>Checking out something from -current (&man.ls.1;) and - deleting it again:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs</userinput> -&prompt.user; <userinput>cvs co ls</userinput> -&prompt.user; <userinput>cvs release -d ls</userinput></screen> - </example> - - <example> - <title>Checking out the version of ls(1) in the 2.2-stable - branch:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs</userinput> -&prompt.user; <userinput>cvs co -rRELENG_2_2 ls</userinput> -&prompt.user; <userinput>cvs release -d ls</userinput></screen> - </example> - - <example> - <title>Creating a list of changes (as unidiffs) to &man.ls.1;</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs</userinput> -&prompt.user; <userinput>cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls</userinput></screen> - </example> - - <example> - <title>Finding out what other module names can be used:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs</userinput> -&prompt.user; <userinput>cvs co modules</userinput> -&prompt.user; <userinput>more modules/modules</userinput> -&prompt.user; <userinput>cvs release -d modules</userinput></screen> - </example> - </sect3> - - <sect3> - <title>Other Resources</title> - - <para>The following additional resources may be helpful in learning - CVS:</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/cvs/">CVS Tutorial</ulink> from Cal Poly.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.cyclic.com">Cyclic Software</ulink>, - commercial maintainers of CVS.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVSWeb</ulink> is - the FreeBSD Project web interface for CVS.</para> - </listitem> - </itemizedlist> - </sect3> - </sect2> - - <sect2 id="ctm"> - <title><application>CTM</application></title> - - <para><emphasis>Contributed by &a.phk;. Updated - 19-October-1997.</emphasis></para> - - <para><application>CTM</application> is a method for keeping a remote - directory tree in sync with a central one. It has been developed for - usage with FreeBSD's source trees, though other people may find it - useful for other purposes as time goes by. Little, if any, - documentation currently exists at this time on the process of creating - deltas, so talk to &a.phk; for more information should you wish to use - <application>CTM</application> for other things.</para> - - <sect3> - <title>Why should I use <application>CTM</application>?</title> - - <para><application>CTM</application> will give you a local copy of the - FreeBSD source trees. There are a number of “flavors” - of the tree available. Whether you wish to track the entire cvs - tree or just one of the branches, <application>CTM</application> can - provide you the information. If you are an active developer on - FreeBSD, but have lousy or non-existent TCP/IP connectivity, or - simply wish to have the changes automatically sent to you, - <application>CTM</application> was made for you. You will need to - obtain up to three deltas per day for the most active branches. - However, you should consider having them sent by automatic email. - The sizes of the updates are always kept as small as possible. This - is typically less than 5K, with an occasional (one in ten) being - 10-50K and every now and then a biggie of 100K+ or more coming - around.</para> - - <para>You will also need to make yourself aware of the various caveats - related to working directly from the development sources rather than - a pre-packaged release. This is particularly true if you choose the - “current” sources. It is recommended that you read - <link linkend="current">Staying current with FreeBSD</link>.</para> - </sect3> - - <sect3> - <title>What do I need to use <application>CTM</application>?</title> - - <para>You will need two things: The <application>CTM</application> - program and the initial deltas to feed it (to get up to - “current” levels).</para> - - <para>The <application>CTM</application> program has been part of - FreeBSD ever since version 2.0 was released, and lives in - <filename>/usr/src/usr.sbin/CTM</filename> if you have a copy of the - source online.</para> - - <para>If you are running a pre-2.0 version of FreeBSD, you can fetch - the current <application>CTM</application> sources directly - from:</para> - - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm</ulink></para> - - <para>The “deltas” you feed <application>CTM</application> - can be had two ways, FTP or e-mail. If you have general FTP access - to the Internet then the following FTP sites support access to - <application>CTM</application>:</para> - - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM">ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM</ulink></para> - - <para>or see section <link linkend="mirrors-ctm">mirrors</link>.</para> - - <para>FTP the relevant directory and fetch the - <filename>README</filename> file, starting from there.</para> - - <para>If you may wish to get your deltas via email:</para> - - <para>Send email to &a.majordomo; to subscribe to one of the - <application>CTM</application> distribution lists. - “ctm-cvs-cur” supports the entire cvs tree. - “ctm-src-cur” supports the head of the development - branch. “ctm-src-2_2” supports the 2.2 release branch, - etc. (If you do not know how to subscribe yourself using majordomo, - send a message first containing the word <literal>help</literal> - — it will send you back usage instructions.)</para> - - <para>When you begin receiving your <application>CTM</application> - updates in the mail, you may use the <command>ctm_rmail</command> - program to unpack and apply them. You can actually use the - <command>ctm_rmail</command> program directly from a entry in - <filename>/etc/aliases</filename> if you want to have the process - run in a fully automated fashion. Check the - <command>ctm_rmail</command> man page for more details.</para> - - <note> - <para>No matter what method you use to get the - <application>CTM</application> deltas, you should subscribe to the - <email>ctm-announce@FreeBSD.org</email> mailing list. In the - future, this will be the only place where announcements concerning - the operations of the <application>CTM</application> system will - be posted. Send an email to &a.majordomo; with a single line of - <literal>subscribe ctm-announce</literal> to get added to the - list.</para> - </note> - </sect3> - - <sect3> - <title>Starting off with <application>CTM</application> for the first - time</title> - - <para>Before you can start using <application>CTM</application> - deltas, you will need to get to a starting point for the deltas - produced subsequently to it.</para> - - <para>First you should determine what you already have. Everyone can - start from an “empty” directory. You must use an - initial “Empty&rdquo delta to start off your - <application>CTM</application> supported tree. At some point it is - intended that one of these “started” deltas be - distributed on the CD for your convenience. This does not currently - happen however.</para> - - <para>However, since the trees are many tens of megabytes, you should - prefer to start from something already at hand. If you have a - RELEASE CD, you can copy or extract an initial source from it. This - will save a significant transfer of data.</para> - - <para>You can recognize these “starter” deltas by the - <literal>X</literal> appended to the number - (<filename>src-cur.3210XEmpty.gz</filename> for instance). The - designation following the <filename>X</filename> corresponds to the - origin of your initial “seed”. - <filename>Empty</filename> is an empty directory. As a rule a base - transition from <filename>Empty</filename> is produced every 100 - deltas. By the way, they are large! 25 to 30 Megabytes of - <command>gzip</command>'ed data is common for the - <filename>XEmpty</filename> deltas.</para> - - <para>Once you've picked a base delta to start from, you will also - need all deltas with higher numbers following it.</para> - </sect3> - - <sect3> - <title>Using <application>CTM</application> in your daily life</title> - - <para>To apply the deltas, simply say:</para> - - <screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput> -&prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen> - - <para><application>CTM</application> understands deltas which have - been put through <command>gzip</command>, so you do not need to - gunzip them first, this saves disk space.</para> - - <para>Unless it feels very secure about the entire process, - <application>CTM</application> will not touch your tree. To verify - a delta you can also use the <option>-c</option> flag and - <application>CTM</application> will not actually touch your tree; it - will merely verify the integrity of the delta and see if it would - apply cleanly to your current tree.</para> - - <para>There are other options to <application>CTM</application> as - well, see the manual pages or look in the sources for more - information.</para> - - <para>I would also be very happy if somebody could help with the - “user interface” portions, as I have realized that I - cannot make up my mind on what options should do what, how and - when...</para> - - <para>That's really all there is to it. Every time you get a new - delta, just run it through <application>CTM</application> to keep - your sources up to date.</para> - - <para>Do not remove the deltas if they are hard to download again. You - just might want to keep them around in case something bad happens. - Even if you only have floppy disks, consider using - <command>fdwrite</command> to make a copy.</para> - </sect3> - - <sect3> - <title>Keeping your local changes</title> - - <para>As a developer one would like to experiment with and change - files in the source tree. <application>CTM</application> supports - local modifications in a limited way: before checking for the - presence of a file <filename>foo</filename>, it first looks for - <filename>foo.ctm</filename>. If this file exists, CTM will operate - on it instead of <filename>foo</filename>.</para> - - <para>This behaviour gives us a simple way to maintain local changes: - simply copy the files you plan to modify to the corresponding file - names with a <filename>.ctm</filename> suffix. Then you can freely - hack the code, while CTM keeps the <filename>.ctm</filename> file - up-to-date.</para> - </sect3> - - <sect3> - <title>Other interesting <application>CTM</application> options</title> - - <sect4> - <title>Finding out exactly what would be touched by an - update</title> - - <para>You can determine the list of changes that - <application>CTM</application> will make on your source repository - using the <option>-l</option> option to - <application>CTM</application>.</para> - - <para>This is useful if you would like to keep logs of the changes, - pre- or post- process the modified files in any manner, or just - are feeling a tad paranoid <!-- smiley -->:-).</para> - </sect4> - - <sect4> - <title>Making backups before updating</title> - - <para>Sometimes you may want to backup all the files that would be - changed by a <application>CTM</application> update.</para> - - <para>Specifying the <option>-B backup-file</option> option causes - <application>CTM</application> to backup all files that would be - touched by a given <application>CTM</application> delta to - <filename>backup-file</filename>.</para> - </sect4> - - <sect4> - <title>Restricting the files touched by an update</title> - - <para>Sometimes you would be interested in restricting the scope of - a given <application>CTM</application> update, or may be - interested in extracting just a few files from a sequence of - deltas.</para> - - <para>You can control the list of files that - <application>CTM</application> would operate on by specifying - filtering regular expressions using the <option>-e</option> and - <option>-x</option> options.</para> - - <para>For example, to extract an up-to-date copy of - <filename>lib/libc/Makefile</filename> from your collection of - saved CTM deltas, run the commands:</para> - - <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput> -&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen> - - <para>For every file specified in a <application>CTM</application> - delta, the <option>-e</option> and <option>-x</option> options are - applied in the order given on the command line. The file is - processed by <application>CTM</application> only if it is marked - as eligible after all the <option>-e</option> and - <option>-x</option> options are applied to it.</para> - </sect4> - </sect3> - - <sect3> - <title>Future plans for <application>CTM</application></title> - - <para>Tons of them:</para> - - <itemizedlist> - <listitem> - <para>Use some kind of authentication into the CTM system, so as - to allow detection of spoofed CTM updates.</para> - </listitem> - - <listitem> - <para>Clean up the options to <application>CTM</application>, they - became confusing and counter intuitive.</para> - </listitem> - </itemizedlist> - - <para>The bad news is that I am very busy, so any help in doing this - will be most welcome. And do not forget to tell me what you want - also...</para> - </sect3> - - <sect3> - <title>Miscellaneous stuff</title> - - <para>All the “DES infected” (e.g. export controlled) - source is not included. You will get the - “international” version only. If sufficient interest - appears, we will set up a <literal>sec-cur</literal> sequence too. - There is a sequence of deltas for the <literal>ports</literal> - collection too, but interest has not been all that high yet. Tell me - if you want an email list for that too and we will consider setting - it up.</para> - </sect3> - - <sect3> - <title>Thanks!</title> - - <variablelist> - <varlistentry> - <term>&a.bde;</term> - - <listitem> - <para>for his pointed pen and invaluable comments.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.sos;</term> - - <listitem> - <para>for patience.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Stephen McKay</term> - - <listitem> - <para>wrote <command>ctm_[rs]mail</command>, much - appreciated.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.jkh;</term> - - <listitem> - <para>for being so stubborn that I had to make it better.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>All the users</term> - - <listitem> - <para>I hope you like it...</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - </sect2> - - <sect2 id="cvsup"> - <title><application>CVSup</application></title> - - <para><emphasis>Contributed by &a.jdp;</emphasis>.</para> - - <sect3 id="cvsup-intro"> - <title>Introduction</title> - - <para><application>CVSup</application> is a software package for - distributing and updating source trees from a master CVS repository - on a remote server host. The FreeBSD sources are maintained in a - CVS repository on a central development machine in California. With - <application>CVSup</application>, FreeBSD users can easily keep - their own source trees up to date.</para> - - <para><application>CVSup</application> uses the so-called - <emphasis>pull</emphasis> model of updating. Under the pull model, - each client asks the server for updates, if and when they are - wanted. The server waits passively for update requests from its - clients. Thus all updates are instigated by the client. The server - never sends unsolicited updates. Users must either run the - <application>CVSup</application> client manually to get an update, - or they must set up a <command>cron</command> job to run it - automatically on a regular basis.</para> - - <para>The term <application>CVSup</application>, capitalized just so, - refers to the entire software package. Its main components are the - client <command>cvsup</command> which runs on each user's machine, - and the server <command>cvsupd</command> which runs at each of the - FreeBSD mirror sites.</para> - - <para>As you read the FreeBSD documentation and mailing lists, you may - see references to <application>sup</application>. - <application>Sup</application> was the predecessor of - <application>CVSup</application>, and it served a similar purpose. - <application>CVSup</application> is in used in much the same way as - sup and, in fact, uses configuration files which are - backward-compatible with <command>sup</command>'s. - <application>Sup</application> is no longer used in the FreeBSD - project, because <application>CVSup</application> is both faster and - more flexible.</para> - </sect3> - - <sect3 id="cvsup-install"> - <title>Installation</title> - - <para>The easiest way to install <application>CVSup</application> if - you are running FreeBSD 2.2 or later is to use either <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports-current/net/cvsup.tar">the - port</ulink> from the FreeBSD <link linkend="ports">ports - collection</link> or the corresponding <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/packages-current/net/cvsup-16.0.tgz">binary - package</ulink>, depending on whether you prefer to roll your own - or not.</para> - - <para>If you are running FreeBSD-2.1.6 or 2.1.7, you unfortunately - cannot use the binary package versions due to the fact that they - require a version of the C library that does not yet exist in - FreeBSD-2.1.{6,7}. You can easily use <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports-current/net/cvsup.tar">the - port</ulink>, however, just as with FreeBSD 2.2. Simply unpack - the tar file, cd to the cvsup subdirectory and type <command>make - install</command>.</para> - - <para>Because <application>CVSup</application> is written in <ulink - URL="http://www.research.digital.com/SRC/modula-3/html/home.html">Modula-3</ulink>, - both the package and the port require that the Modula-3 runtime - libraries be installed. These are available as the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports-current/lang/modula-3-lib.tar">lang/modula-3-lib</ulink> port and the <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/packages-current/lang/modula-3-lib-3.6.tgz">lang/modula-3-lib-3.6</ulink> package. - If you follow the same directions as for <command>cvsup</command>, - these libraries will be compiled and/or installed automatically when - you install the <application>CVSup</application> port or - package.</para> - - <para>The Modula-3 libraries are rather large, and fetching and - compiling them is not an instantaneous process. For that reason, a - third option is provided. You can get <emphasis>statically - linked</emphasis> FreeBSD executables for - <application>CVSup</application> from the USA distribution - site:</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup-bin-16.0.tar.gz">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup-bin-16.0.tar.gz</ulink> (client including GUI).</para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-16.0.tar.gz">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-16.0.tar.gz</ulink> (client without GUI).</para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupd-bin-16.0.tar.gz">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupd-bin-16.0.tar.gz</ulink> (server).</para> - </listitem> - </itemizedlist> - - <para>as well as from the many FreeBSD <link linkend="mirrors-ftp">FTP - mirror sites</link> around the world.</para> - - <para>Most users will need only the client. These executables are - entirely self-contained, and they will run on any version of FreeBSD - from FreeBSD-2.1.0 to FreeBSD-current.</para> - - <para>In summary, your options for installing CVSup are:</para> - - <itemizedlist> - <listitem> - <para>FreeBSD-2.2 or later: static binary, port, or - package</para> - </listitem> - - <listitem> - <para>FreeBSD-2.1.6, 2.1.7: static binary or port</para> - </listitem> - - <listitem> - <para>FreeBSD-2.1.5 or earlier: static binary</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3 id="cvsup-config"> - <title>CVSup Configuration</title> - - <para><application>CVSup</application>'s operation is controlled by a - configuration file called the <filename>supfile</filename>. - Beginning with FreeBSD-2.2, there are some sample - <filename>supfiles</filename> in the directory <ulink - URL="file:/usr/share/examples/cvsup">/usr/share/examples/cvsup</ulink>. - These examples are also available from <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/</ulink> if you are on a pre-2.2 system.</para> - - <para>The information in a <filename>supfile</filename> answers the - following questions for cvsup:</para> - - <itemizedlist> - <listitem> - <para><link linkend="cvsup-config-files">Which files do you want - to receive?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-vers">Which versions of them do - you want?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-where">Where do you want to get - them from?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-dest">Where do you want to put - them on your own machine?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-status">Where do you want to put - your status files?</link></para> - </listitem> - </itemizedlist> - - <para>In the following sections, we will construct a typical - <filename>supfile</filename> by answering each of these questions in - turn. First, we describe the overall structure of a - <filename>supfile</filename>.</para> - - <para>A <filename>supfile</filename> is a text file. Comments begin - with <literal>#</literal> and extend to the end of the line. Lines - that are blank and lines that contain only comments are - ignored.</para> - - <para>Each remaining line describes a set of files that the user - wishes to receive. The line begins with the name of a - “collection”, a logical grouping of files defined by the - server. The name of the collection tells the server which files you - want. After the collection name come zero or more fields, separated - by white space. These fields answer the questions listed above. - There are two types of fields: flag fields and value fields. A flag - field consists of a keyword standing alone, e.g., - <literal>delete</literal> or <literal>compress</literal>. A value - field also begins with a keyword, but the keyword is followed - without intervening white space by <literal>=</literal> and a second - word. For example, <literal>release=cvs</literal> is a value - field.</para> - - <para>A <filename>supfile</filename> typically specifies more than one - collection to receive. One way to structure a - <filename>supfile</filename> is to specify all of the relevant - fields explicitly for each collection. However, that tends to make - the <filename>supfile</filename> lines quite long, and it is - inconvenient because most fields are the same for all of the - collections in a <filename>supfile</filename>. - <application>CVSup</application> provides a defaulting mechanism to - avoid these problems. Lines beginning with the special - pseudo-collection name <literal>*default</literal> can be used to - set flags and values which will be used as defaults for the - subsequent collections in the <filename>supfile</filename>. A - default value can be overridden for an individual collection, by - specifying a different value with the collection itself. Defaults - can also be changed or augmented in mid-supfile by additional - <literal>*default</literal> lines.</para> - - <para>With this background, we will now proceed to construct a - <filename>supfile</filename> for receiving and updating the main - source tree of <link - linkend="current">FreeBSD-current</link>.</para> - - <itemizedlist> - <listitem> - <para>Which files do you want to receive?<anchor - id="cvsup-config-files"></para> - - <para>The files available via <application>CVSup</application> are - organized into named groups called “collections”. - The collections that are available are described <link - linkend="cvsup-collec">here</link>. In this example, we wish - to receive the entire main source tree for the FreeBSD system. - There is a single large collection <literal>src-all</literal> - which will give us all of that, except the export-controlled - cryptography support. Let us assume for this example that we - are in the USA or Canada. Then we can get the cryptography code - with one additional collection, <literal>cvs-crypto</literal>. - As a first step toward constructing our - <filename>supfile</filename>, we simply list these collections, - one per line:</para> - - <programlisting> -src-all -cvs-crypto</programlisting> - </listitem> - - <listitem> - <para>Which version(s) of them do you want?<anchor - id="cvsup-config-vers"></para> - - <para>With <application>CVSup</application>, you can receive - virtually any version of the sources that ever existed. That is - possible because the cvsupd server works directly from the CVS - repository, which contains all of the versions. You specify - which one of them you want using the <literal>tag=</literal> and - <option>date=</option> value fields.</para> - - <warning> - <para>Be very careful to specify any <literal>tag=</literal> - fields correctly. Some tags are valid only for certain - collections of files. If you specify an incorrect or - misspelled tag, CVSup will delete files which you probably do - not want deleted. In particular, use <emphasis>only - </emphasis> <literal>tag=.</literal> for the - <literal>ports-*</literal> collections.</para> - </warning> - - <para>The <literal>tag=</literal> field names a symbolic tag in - the repository. There are two kinds of tags, revision tags and - branch tags. A revision tag refers to a specific revision. Its - meaning stays the same from day to day. A branch tag, on the - other hand, refers to the latest revision on a given line of - development, at any given time. Because a branch tag does not - refer to a specific revision, it may mean something different - tomorrow than it means today.</para> - - <para>Here are the branch tags that users might be interested - in:</para> - - <variablelist> - <varlistentry> - <term>tag=.</term> - - <listitem> - <para>The main line of development, also known as - FreeBSD-current.</para> - - <note> - <para>The <literal>.</literal> is not punctuation; it is - the name of the tag. Valid for all collections.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3</term> - - <listitem> - <para>The line of development for FreeBSD-3.x, also known as - FreeBSD-stable. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2</term> - - <listitem> - <para>The line of development for FreeBSD-2.2.x, also known - as 2.2-stable. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_1_0</term> - - <listitem> - <para>The line of development for FreeBSD-2.1.x - this - branch is largely obsolete. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Here are the revision tags that users might be interested - in:</para> - - <variablelist> - <varlistentry> - - <term>tag=RELENG_3_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.2. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.1. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3_0_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.0. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_8_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.8. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.7. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.6. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.5. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_2_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.2. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.1. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.0. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_1_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.7. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_1_6_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.6.1. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_1_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.6. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_1_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.5. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.0. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - </variablelist> - - <warning> - <para>Be very careful to type the tag name exactly as shown. - <application>CVSup</application> cannot distinguish between - valid and invalid tags. If you misspell the tag, - <application>CVSup</application> will behave as though you had - specified a valid tag which happens to refer to no files at - all. It will delete your existing sources in that - case.</para> - </warning> - - <para>When you specify a branch tag, you normally receive the - latest versions of the files on that line of development. If - you wish to receive some past version, you can do so by - specifying a date with the <option>date=</option> value field. - The &man.cvsup.1; manual page explains how to do - that.</para> - - <para>For our example, we wish to receive FreeBSD-current. We add - this line at the beginning of our - <filename>supfile</filename>:</para> - - <programlisting> -*default tag=.</programlisting> - - <para>There is an important special case that comes into play if - you specify neither a <literal>tag=</literal> field nor a - <literal>date=</literal> field. In that case, you receive the - actual RCS files directly from the server's CVS repository, - rather than receiving a particular version. Developers - generally prefer this mode of operation. By maintaining a copy - of the repository itself on their systems, they gain the ability - to browse the revision histories and examine past versions of - files. This gain is achieved at a large cost in terms of disk - space, however.</para> - </listitem> - - <listitem> - <para>Where do you want to get them from?<anchor - id="cvsup-config-where"></para> - - <para>We use the <literal>host=</literal> field to tell - <command>cvsup</command> where to obtain its updates. Any of - the <link linkend="mirrors-cvsup">CVSup mirror sites</link> will - do, though you should try to select one that is close to you in - cyberspace. In this example we will use a fictional FreeBSD - distribution site, <hostid - role="fqdn">cvsup666.FreeBSD.org</hostid>:</para> - - <programlisting> -*default host=cvsup666.FreeBSD.org</programlisting> - - <para>You will need to change the host to one that actually exists - before running CVSup. On any particular run of - <command>cvsup</command>, you can override the host setting on - the command line, with <option>-h - <replaceable>hostname</replaceable></option>.</para> - </listitem> - - <listitem> - <para>Where do you want to put them on your own machine?<anchor - id="cvsup-config-dest"></para> - - <para>The <literal>prefix=</literal> field tells - <command>cvsup</command> where to put the files it receives. In - this example, we will put the source files directly into our - main source tree, <filename>/usr/src</filename>. The - <filename>src</filename> directory is already implicit in the - collections we have chosen to receive, so this is the correct - specification:</para> - - <programlisting> -*default prefix=/usr</programlisting> - </listitem> - - <listitem> - <para>Where should <command>cvsup</command> maintain its status - files?<anchor id="cvsup-config-status"></para> - - <para>The cvsup client maintains certain status files in what is - called the “base” directory. These files help - <application>CVSup</application> to work more efficiently, by - keeping track of which updates you have already received. We - will use the standard base directory, - <filename>/usr/local/etc/cvsup</filename>:</para> - - <programlisting> -*default base=/usr/local/etc/cvsup</programlisting> - - <para>This setting is used by default if it is not specified in - the <filename>supfile</filename>, so we actually do not need the - above line.</para> - - <para>If your base directory does not already exist, now would be - a good time to create it. The <command>cvsup</command> client - will refuse to run if the base directory does not exist.</para> - </listitem> - - <listitem> - <para>Miscellaneous <filename>supfile</filename> settings:</para> - - <para>There is one more line of boiler plate that normally needs - to be present in the <filename>supfile</filename>:</para> - - <programlisting> -*default release=cvs delete use-rel-suffix compress</programlisting> - - <para><literal>release=cvs</literal> indicates that the server - should get its information out of the main FreeBSD CVS - repository. This is virtually always the case, but there are - other possibilities which are beyond the scope of this - discussion.</para> - - <para><literal>delete</literal> gives - <application>CVSup</application> permission to delete files. - You should always specify this, so that - <application>CVSup</application> can keep your source tree fully - up to date. <application>CVSup</application> is careful to - delete only those files for which it is responsible. Any extra - files you happen to have will be left strictly alone.</para> - - <para><literal>use-rel-suffix</literal> is ... arcane. If you - really want to know about it, see the &man.cvsup.1; manual page. - Otherwise, just specify it and do not worry about it.</para> - - <para><literal>compress</literal> enables the use of gzip-style - compression on the communication channel. If your network link - is T1 speed or faster, you probably should not use compression. - Otherwise, it helps substantially.</para> - </listitem> - - <listitem> - <para>Putting it all together:</para> - - <para>Here is the entire <filename>supfile</filename> for our - example:</para> - - <programlisting> -*default tag=. -*default host=cvsup666.FreeBSD.org -*default prefix=/usr -*default base=/usr/local/etc/cvsup -*default release=cvs delete use-rel-suffix compress - -src-all -cvs-crypto</programlisting> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Running <application>CVSup</application></title> - - <para>You are now ready to try an update. The command line for doing - this is quite simple:</para> - - <screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen> - - <para>where <filename><replaceable>supfile</replaceable></filename> is - of course the name of the supfile you have just created. Assuming - you are running under X11, <command>cvsup</command> will display a - GUI window with some buttons to do the usual things. Press the - “go” button, and watch it run.</para> - - <para>Since you are updating your actual <filename>/usr/src</filename> - tree in this example, you will need to run the program as - <username>root</username> so that <command>cvsup</command> has the - permissions it needs to update your files. Having just created your - configuration file, and having never used this program before, that - might understandably make you nervous. There is an easy way to do a - trial run without touching your precious files. Just create an - empty directory somewhere convenient, and name it as an extra - argument on the command line:</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput> -&prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen> - - <para>The directory you specify will be used as the destination - directory for all file updates. <application>CVSup</application> - will examine your usual files in <filename>/usr/src</filename>, but - it will not modify or delete any of them. Any file updates will - instead land in <filename>/var/tmp/dest/usr/src</filename>. - <application>CVSup</application> will also leave its base directory - status files untouched when run this way. The new versions of those - files will be written into the specified directory. As long as you - have read access to <filename>/usr/src</filename>, you do not even - need to be root to perform this kind of trial run.</para> - - <para>If you are not running X11 or if you just do not like GUIs, you - should add a couple of options to the command line when you run - cvsup:</para> - - <screen>&prompt.root; <userinput>cvsup -g -L 2 supfile</userinput></screen> - - <para>The <option>-g</option> tells cvsup not to use its GUI. This is - automatic if you are not running X11, but otherwise you have to - specify it.</para> - - <para>The <option>-L 2</option> tells cvsup to print out the details - of all the file updates it is doing. There are three levels of - verbosity, from <option>-L 0</option> to <option>-L 2</option>. The - default is 0, which means total silence except for error - messages.</para> - - <para>There are plenty of other options available. For a brief list - of them, type <command>cvsup -H</command>. For more detailed - descriptions, see the manual page.</para> - - <para>Once you are satisfied with the way updates are working, you can - arrange for regular runs of cvsup using &man.cron.8;. - Obviously, you should not let cvsup use its GUI when running it from - cron.</para> - </sect3> - - <sect3 id="cvsup-collec"> - <title><application>CVSup</application> File Collections</title> - - <para>The file collections available via - <application>CVSup</application> are organized hierarchically. - There are a few large collections, and they are divided into smaller - sub-collections. Receiving a large collection is equivalent to - receiving each of its sub-collections. The hierarchical - relationships among collections are reflected by the use of - indentation in the list below.</para> - - <para>The most commonly used collections are - <literal>src-all</literal>, <literal>cvs-crypto</literal>, and - <literal>ports-all</literal>. The other collections are used only - by small groups of people for specialized purposes, and some mirror - sites may not carry all of them.</para> - - <variablelist> - <varlistentry> - <term><literal>cvs-all release=cvs</literal></term> - - <listitem> - <para>The main FreeBSD CVS repository, excluding the - export-restricted cryptography code.</para> - - <variablelist> - <varlistentry> - <term><literal>distrib release=cvs</literal></term> - - <listitem> - <para>Files related to the distribution and mirroring of - FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>doc-all release=cvs</literal></term> - - <listitem> - <para>Sources for the FreeBSD handbook and other - documentation.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-all release=cvs</literal></term> - - <listitem> - <para>The FreeBSD ports collection.</para> - - <variablelist> - <varlistentry> - <term><literal>ports-archivers - release=cvs</literal></term> - - <listitem> - <para>Archiving tools.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-astro - release=cvs</literal></term> - - <listitem> - <para>Astronomical ports.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-audio - release=cvs</literal></term> - - <listitem> - <para>Sound support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-base release=cvs</literal></term> - - <listitem> - <para>Miscellaneous files at the top of - /usr/ports.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-benchmarks - release=cvs</literal></term> - - <listitem> - <para>Benchmarks.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-biology - release=cvs</literal></term> - - <listitem> - <para>Biology.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-cad release=cvs</literal></term> - - <listitem> - <para>Computer aided design tools.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-chinese - release=cvs</literal></term> - - <listitem> - <para>Chinese language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-comms - release=cvs</literal></term> - - <listitem> - <para>Communication software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-converters - release=cvs</literal></term> - - <listitem> - <para>character code converters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-databases - release=cvs</literal></term> - - <listitem> - <para>Databases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal></literal>ports-deskutils - release=cvs</term> - - <listitem> - <para>Things that used to be on the desktop before - computers were invented.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-devel - release=cvs</literal></term> - - <listitem> - <para>Development utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-editors - release=cvs</literal></term> - - <listitem> - <para>Editors.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-emulators - release=cvs</literal></term> - - <listitem> - <para>Emulators for other operating systems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-ftp - release=cvs</literal></term> - - <listitem> - <para>FTP client and server utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-games - release=cvs</literal></term> - - <listitem> - <para>Games.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-german - release=cvs</literal></term> - - <listitem> - <para>German language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-graphics - release=cvs</literal></term> - - <listitem> - <para>Graphics utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-japanese - release=cvs</literal></term> - - <listitem> - <para>Japanese language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-korean - release=cvs</literal></term> - - <listitem> - <para>Korean language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-lang release=cvs</literal></term> - - <listitem> - <para>Programming languages.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-mail release=cvs</literal></term> - - <listitem> - <para>Mail software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-math release=cvs</literal></term> - - <listitem> - <para>Numerical computation software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-mbone - release=cvs</literal></term> - - <listitem> - <para>MBone applications.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-misc release=cvs</literal></term> - - <listitem> - <para>Miscellaneous utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-net release=cvs</literal></term> - - <listitem> - <para>Networking software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-news release=cvs</literal></term> - - <listitem> - <para>USENET news software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-palm - release=cvs</literal></term> - - <listitem> - <para>Software support for 3Com Palm(tm) series.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-plan9 - release=cvs</literal></term> - - <listitem> - <para>Various programs from Plan9.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-print - release=cvs</literal></term> - - <listitem> - <para>Printing software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-russian - release=cvs</literal></term> - - <listitem> - <para>Russian language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-security - release=cvs</literal></term> - - <listitem> - <para>Security utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-shells - release=cvs</literal></term> - - <listitem> - <para>Command line shells.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-sysutils - release=cvs</literal></term> - - <listitem> - <para>System utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-textproc - release=cvs</literal></term> - - <listitem> - <para>text processing utilities (does not include - desktop publishing).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-vietnamese - release=cvs</literal></term> - - <listitem> - <para>Vietnamese language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-www release=cvs</literal></term> - - <listitem> - <para>Software related to the World Wide Web.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11 release=cvs</literal></term> - - <listitem> - <para>Ports to support the X window system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-clocks - release=cvs</literal></term> - - <listitem> - <para>X11 clocks.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-fm - release=cvs</literal></term> - - <listitem> - <para>X11 file managers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-fonts - release=cvs</literal></term> - - <listitem> - <para>X11 fonts and font utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-toolkits - release=cvs</literal></term> - - <listitem> - <para>X11 toolkits.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-wm</literal></term> - - <listitem> - <para>X11 window managers.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-all release=cvs</literal></term> - - <listitem> - <para>The main FreeBSD sources, excluding the - export-restricted cryptography code.</para> - - <variablelist> - <varlistentry> - <term><literal>src-base release=cvs</literal></term> - - <listitem> - <para>Miscellaneous files at the top of - <filename>/usr/src</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-bin release=cvs</literal></term> - - <listitem> - <para>User utilities that may be needed in - single-user mode - (<filename>/usr/src/bin</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-contrib - release=cvs</literal></term> - - <listitem> - <para>Utilities and libraries from outside the - FreeBSD project, used relatively unmodified - (<filename>/usr/src/contrib</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-etc release=cvs</literal></term> - - <listitem> - <para>System configuration files - (<filename>/usr/src/etc</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-games release=cvs</literal></term> - - <listitem> - <para>Games - (<filename>/usr/src/games</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-gnu release=cvs</literal></term> - - <listitem> - <para>Utilities covered by the GNU Public License - (<filename>/usr/src/gnu</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-include - release=cvs</literal></term> - - <listitem> - <para>Header files - (<filename>/usr/src/include</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-kerberosIV - release=cvs</literal></term> - - <listitem> - <para>KerberosIV security package - (<filename>/usr/src/kerberosIV</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-lib release=cvs</literal></term> - - <listitem> - <para>Libraries - (<filename>/usr/src/lib</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-libexec - release=cvs</literal></term> - - <listitem> - <para>System programs normally executed by other - programs - (<filename>/usr/src/libexec</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-release - release=cvs</literal></term> - - <listitem> - <para>Files required to produce a FreeBSD release - (<filename>/usr/src/release</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-sbin release=cvs</literal></term> - - <listitem> - <para>System utilities for single-user mode - (<filename>/usr/src/sbin</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-share release=cvs</literal></term> - - <listitem> - <para>Files that can be shared across multiple - systems - (<filename>/usr/src/share</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-sys release=cvs</literal></term> - - <listitem> - <para>The kernel - (<filename>/usr/src/sys</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-tools release=cvs</literal></term> - - <listitem> - <para>Various tools for the maintenance of FreeBSD - (<filename>/usr/src/tools</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-usrbin release=cvs</literal></term> - - <listitem> - <para>User utilities - (<filename>/usr/src/usr.bin</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-usrsbin - release=cvs</literal></term> - - <listitem> - <para>System utilities - (<filename>/usr/src/usr.sbin</filename>).</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>www release=cvs</literal></term> - - <listitem> - <para>The sources for the World Wide Web data.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>cvs-crypto release=cvs</literal></term> - - <listitem> - <para>The export-restricted cryptography code.</para> - - <variablelist> - <varlistentry> - <term><literal>src-crypto release=cvs</literal></term> - - <listitem> - <para>Export-restricted utilities and libraries from - outside the FreeBSD project, used relatively unmodified - (<filename>/usr/src/crypto</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-eBones release=cvs</literal></term> - - <listitem> - <para>Kerberos and DES - (<filename>/usr/src/eBones</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-secure release=cvs</literal></term> - - <listitem> - <para>DES (<filename>/usr/src/secure</filename>).</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>distrib release=self</literal></term> - - <listitem> - <para>The CVSup server's own configuration files. Used by CVSup - mirror sites.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>gnats release=current</literal></term> - - <listitem> - <para>The GNATS bug-tracking database.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>mail-archive release=current</literal></term> - - <listitem> - <para>FreeBSD mailing list archive.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>www release=current</literal></term> - - <listitem> - <para>The installed World Wide Web data. Used by WWW mirror - sites.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3> - <title>For more information</title> - - <para>For the CVSup FAQ and other information about CVSup, see <ulink - url="http://www.polstra.com/projects/freeware/CVSup/">The CVSup - Home Page</ulink>.</para> - - <para>Most FreeBSD-related discussion of - <application>CVSup</application> takes place on the &a.hackers;. - New versions of the software are announced there, as well as on the - &a.announce;.</para> - - <para>Questions and bug reports should be addressed to the author of - the program at <email>cvsup-bugs@polstra.com</email>.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="makeworld"> - <title>Using <command>make world</command> to rebuild your system</title> - - <para><emphasis>Contributed by &a.nik;.</emphasis></para> - - <para>Once you have synchronised your local source tree against a - particular version of FreeBSD (<literal>stable</literal>, - <literal>current</literal> and so on) you must then use the source tree - to rebuild the system.</para> - - <para>Currently, the best source of information on how to do that is a - tutorial available from <ulink - URL="http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html">http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html</ulink>.</para> - - <para>A successor to this tutorial will be integrated into the - handbook.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/disks/chapter.sgml b/en/handbook/disks/chapter.sgml deleted file mode 100644 index cf74febacb..0000000000 --- a/en/handbook/disks/chapter.sgml +++ /dev/null @@ -1,168 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.6 1999-05-16 13:40:15 nik Exp $ ---> - -<chapter id="disks"> - <title>Disks</title> - - <para><emphasis>Contributed by &a.obrien; 26 April 1998</emphasis></para> - - <para>Lets say we want to add a new SCSI disk to a machine that currently - only has a single drive. First turn off the computer and install the - drive in the computer following the instructions of the computer, - controller, and drive manufacturer. Due the wide variations of procedures - to do this, the details are beyond the scope of this document.</para> - - <para>Login as user <username>root</username>. After you've installed the - drive, inspect <filename>/var/run/dmesg.boot</filename> to ensure the new - disk was found. Continuing with our example, the newly added drive will - be <filename>da1</filename> and we want to mount it on - <filename>/1</filename>. (if you are adding an IDE drive substitute - <filename>wd</filename> for <filename>da</filename>)</para> - - <para>Because FreeBSD runs on IBM-PC compatible computers, it must take into - account the PC BIOS partitions. These are different from the traditional - BSD partitions. A PC disk has up to four BIOS partition entries. If the - disk is going to be truly dedicated to FreeBSD, you can use the - <emphasis>dedicated</emphasis> mode. Otherwise, FreeBSD will have to live - with in one of the PC BIOS partitions. FreeBSD calls the PC BIOS - partitions, <emphasis>slices</emphasis> so as not to confuse them with - traditional BSD partitions. You may also use slices on a disk that is - dedicated to FreeBSD, but used in a computer that also has another - operating system installed. This is to not confuse the - <command>fdisk</command> utility of the other operating system.</para> - - <para>In the slice case the drive will be added as - <filename>/dev/da1s1e</filename>. This is read as: SCSI disk, unit number - 1 (second SCSI disk), slice 1 (PC BIOS partition 1), and - <filename>e</filename> BSD partition. In the dedicated case, the drive - will be added simply as <filename>/dev/da1e</filename>.</para> - - <sect1> - <title>Using sysinstall</title> - - <para>You may use <command>/stand/sysinstall</command> to partition and - label a new disk using its easy to use menus. Either login as user - <username>root</username> or use the <command>su</command> command. Run - <command>/stand/sysinstall</command> and enter the - <literal>Configure</literal> menu. With in the <literal>FreeBSD - Configuration Menu</literal>, scroll down and select the - <literal>Partition</literal> item. Next you should be presented with a - list of hard drives installed in your system. If you do not see - <literal>da1</literal> listed, you need to recheck your physical - installation and <command>dmesg</command> output in the file - <filename>/var/run/dmesg.boot</filename>.</para> - - <para>Select <literal>da1</literal> to enter the <literal>FDISK Partition - Editor</literal>. Choose <literal>A</literal> to use the entire disk - for FreeBSD. When asked if you want to <quote>remain cooperative with - any future possible operating systems</quote>, answer - <literal>YES</literal>. Write the changes to the disk using - <command>W</command>. Now exit the FDISK editor using - <command>q</command>. Next you will be asked about the Master Boot - Record. Since you are adding a disk to an already running system, - choose <literal>None</literal>.</para> - - <para>Next enter the <literal>Disk Label Editor</literal>. This is where - you will create the traditional BSD partitions. A disk can have up to - eight partitions, labeled a-h. A few of the partition labels have - special uses. The <literal>a</literal> partition is used for the root - partition (<filename>/</filename>). Thus only your system disk (e.g, - the disk you boot from) should have an <literal>a</literal> partition. - The <literal>b</literal> partition is used for swap partitions, and you - may have many disks with swap partitions. The <literal>c</literal> - partition addresses the entire disk in dedicated mode, or the entire - FreeBSD slice in slice mode. The other partitions are for general - use.</para> - - <para>Sysinstall's Label editor favors the <literal>e</literal> partition - for non-root, non-swap partitions. With in the Label editor, create a - single file system using <command>C</command>. When prompted if this - will be a FS (file system) or swap, choose <literal>FS</literal> and - give a mount point (e.g, <filename>/mnt</filename>). When adding a disk - in post-install mode, Sysinstall will not create entries in - <filename>/etc/fstab</filename> for you, so the mount point you specify - isn't important.</para> - - <para>You are now ready to write the new label to the disk and create a - file system on it. Do this by hitting <command>W</command>. Ignore any - errors from Sysinstall that it could not mount the new partition. Exit - the Label Editor and Sysinstall completely.</para> - - <para>The last step is to edit <filename>/etc/fstab</filename> to add an - entry for your new disk.</para> - </sect1> - - <sect1> - <title>Using command line utilities</title> - - <sect2> - <title>* Using Slices</title> - - <para></para> - </sect2> - - <sect2> - <title>Dedicated</title> - - <para>If you will not be sharing the new drive with another operating - system, you may use the <literal>dedicated</literal> mode. Remember - this mode can confuse Microsoft operating systems; however, no damage - will be done by them. IBM's OS/2 however, will - “appropriate” any partition it finds which it doesn't - understand.</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda1 bs=1k count=1</userinput> -&prompt.root; <userinput>disklabel -Brw da1 auto</userinput> -&prompt.root; <userinput>disklabel -e da1</userinput> # create the `e' partition -&prompt.root; <userinput>newfs -d0 /dev/rda1e</userinput> -&prompt.root; <userinput>mkdir -p /1</userinput> -&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e -&prompt.root; <userinput>mount /1</userinput></screen> - - <para>An alternate method is:</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda1 count=2</userinput> -&prompt.root; <userinput>disklabel /dev/rda1 | disklabel -BrR da1 /dev/stdin</userinput> -&prompt.root; <userinput>newfs /dev/rda1e</userinput> -&prompt.root; <userinput>mkdir -p /1</userinput> -&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e -&prompt.root; <userinput>mount /1</userinput></screen> - </sect2> - </sect1> - - <sect1> - <title>* Non-traditional Drives</title> - - <sect2> - <title>* Zip Drives</title> - - <para></para> - </sect2> - - <sect2> - <title>* Jaz Drives</title> - - <para></para> - </sect2> - - <sect2> - <title>* Sequest Drives</title> - - <para></para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> diff --git a/en/handbook/eresources/chapter.sgml b/en/handbook/eresources/chapter.sgml deleted file mode 100644 index 451a3990db..0000000000 --- a/en/handbook/eresources/chapter.sgml +++ /dev/null @@ -1,1378 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.24 1999-08-09 10:04:54 wosch Exp $ ---> - -<chapter id="eresources"> - <title>Resources on the Internet</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <para>The rapid pace of FreeBSD progress makes print media impractical as a - means of 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.</para> - - <para>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.</para> - - <sect1 id="eresources-mail"> - <title>Mailing lists</title> - - <para>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 - <literal>comp.unix.bsd.freebsd.*</literal> 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.</para> - - <para>The charters for the various lists are given at the bottom of this - document. <emphasis>Please read the charter before joining or sending - mail to any list</emphasis>. Most of our list subscribers now receive - many hundreds of FreeBSD related messages every day, and by setting down - charters and rules for proper use we are striving to keep the - signal-to-noise ratio of the lists high. To do less would see the - mailing lists ultimately fail as an effective communications medium for - the project.</para> - - <para>Archives are kept for all of the mailing lists and can be searched - using the <ulink url="http://www.FreeBSD.org/search.html">FreeBSD World - Wide Web server</ulink>. The keyword searchable archive offers an - excellent way of finding answers to frequently asked questions and - should be consulted before posting a question.</para> - - <sect2 id="eresources-summary"> - <title>List summary</title> - - <para><emphasis>General lists:</emphasis> The following are general - lists which anyone is free (and encouraged) to join:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>List</entry> - <entry>Purpose</entry> - </row> - </thead> - - <tbody> - <row> - <entry>freebsd-advocacy</entry> - <entry>FreeBSD Evangelism</entry> - </row> - - <row> - <entry>freebsd-announce</entry> - <entry>Important events and project milestones</entry> - </row> - - <row> - <entry>freebsd-bugs</entry> - <entry>Bug reports</entry> - </row> - - <row> - <entry>freebsd-chat</entry> - <entry>Non-technical items related to the FreeBSD - community</entry> - </row> - - <row> - <entry>freebsd-current</entry> - <entry>Discussion concerning the use of - FreeBSD-current</entry> - </row> - - <row> - <entry>freebsd-isp</entry> - <entry>Issues for Internet Service Providers using - FreeBSD</entry> - </row> - - <row> - <entry>freebsd-jobs</entry> - <entry>FreeBSD employment and consulting - opportunities</entry> - </row> - - <row> - <entry>freebsd-newbies</entry> - <entry>New FreeBSD users activities and discussions</entry> - </row> - - <row> - <entry>freebsd-policy</entry> - <entry>FreeBSD Core team policy decisions. Low volume, and - read-only</entry> - </row> - - <row> - <entry>freebsd-questions</entry> - <entry>User questions and technical support</entry> - </row> - - <row> - <entry>freebsd-stable</entry> - <entry>Discussion concerning the use of - FreeBSD-stable</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para><emphasis>Technical lists:</emphasis> The following lists are for - technical discussion. You should read the charter for each list - carefully before joining or sending mail to one as there are firm - guidelines for their use and content.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>List</entry> - <entry>Purpose</entry> - </row> - </thead> - - <tbody> - <row> - <entry>freebsd-afs</entry> - <entry>Porting AFS to FreeBSD</entry> - </row> - - <row> - <entry>freebsd-alpha</entry> - <entry>Porting FreeBSD to the Alpha</entry> - </row> - - <row> - <entry>freebsd-doc</entry> - <entry>Creating FreeBSD related documents</entry> - </row> - - <row> - <entry>freebsd-database</entry> - <entry>Discussing database use and development under - FreeBSD</entry> - </row> - - <row> - <entry>freebsd-emulation</entry> - <entry>Emulation of other systems such as - Linux/DOS/Windows</entry> - </row> - - <row> - <entry>freebsd-fs</entry> - <entry>Filesystems</entry> - </row> - - <row> - <entry>freebsd-hackers</entry> - <entry>General technical discussion</entry> - </row> - - <row> - <entry>freebsd-hardware</entry> - <entry>General discussion of hardware for running - FreeBSD</entry> - </row> - - <row> - <entry>freebsd-ipfw</entry> - <entry>Technical discussion concerning the redesign of the IP - firewall code</entry> - </row> - - <row> - <entry>freebsd-isdn</entry> - <entry>ISDN developers</entry> - </row> - - <row> - <entry>freebsd-java</entry> - <entry>Java developers and people porting JDKs to - FreeBSD</entry> - </row> - - <row> - <entry>freebsd-mobile</entry> - <entry>Discussions about mobile computing</entry> - </row> - - <row> - <entry>freebsd-mozilla</entry> - <entry>Porting mozilla to FreeBSD</entry> - </row> - - <row> - <entry>freebsd-net</entry> - <entry>Networking discussion and TCP/IP/source code</entry> - </row> - - <row> - <entry>freebsd-platforms</entry> - <entry>Concerning ports to non-Intel architecture - platforms</entry> - </row> - - <row> - <entry>freebsd-ports</entry> - <entry>Discussion of the ports collection</entry> - </row> - - <row> - <entry>freebsd-scsi</entry> - <entry>The SCSI subsystem</entry> - </row> - - <row> - <entry>freebsd-security</entry> - <entry>Security issues</entry> - </row> - - <row> - <entry>freebsd-small</entry> - <entry>Using FreeBSD in embedded applications</entry> - </row> - - <row> - <entry>freebsd-smp</entry> - <entry>Design discussions for [A]Symmetric - MultiProcessing</entry> - </row> - - <row> - <entry>freebsd-sparc</entry> - <entry>Porting FreeBSD to Sparc systems</entry> - </row> - - <row> - <entry>freebsd-tokenring</entry> - <entry>Support Token Ring in FreeBSD</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para><emphasis>Limited lists:</emphasis> The following lists require - approval from <email>core@FreeBSD.org</email> to join, though anyone - is free to send messages to them which fall within the scope of their - charters. It is also a good idea establish a presence in the - technical lists before asking to join one of these limited - lists.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>List</entry> - <entry>Purpose</entry> - </row> - </thead> - - <tbody> - <row> - <entry>freebsd-admin</entry> - <entry>Administrative issues</entry> - </row> - - <row> - <entry>freebsd-arch</entry> - <entry>Architecture and design discussions</entry> - </row> - - <row> - <entry>freebsd-core</entry> - <entry>FreeBSD core team</entry> - </row> - - <row> - <entry>freebsd-hubs</entry> - <entry>People running mirror sites (infrastructural - support)</entry> - </row> - - <row> - <entry>freebsd-install</entry> - <entry>Installation development</entry> - </row> - - <row> - <entry>freebsd-security-notifications</entry> - <entry>Security notifications</entry> - </row> - - <row> - <entry>freebsd-user-groups</entry> - <entry>User group coordination</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para><emphasis>CVS lists:</emphasis> The following lists are for people - interested in seeing the log messages for changes to various areas of - the source tree. They are <emphasis>Read-Only</emphasis> lists and - should not have mail sent to them.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>List</entry> - <entry>Source area</entry> - <entry>Area Description (source for)</entry> - </row> - </thead> - - <tbody> - <row> - <entry>cvs-all</entry> - <entry>/usr/src</entry> - <entry>All changes to the tree (superset)</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2 id="eresources-subscribe"> - <title>How to subscribe</title> - - <para>All mailing lists live on <hostid - role="fqdn">FreeBSD.org</hostid>, so to post to a given list you - simply mail to - <<replaceable>listname</replaceable>@FreeBSD.org>. It will then - be redistributed to mailing list members world-wide.</para> - - <para>To subscribe to a list, send mail to &a.majordomo; and include - - <programlisting> -subscribe <listname> [<optional address>]</programlisting> - - in the body of your message. For example, to subscribe yourself to - <literal>freebsd-announce</literal>, you'd do:</para> - - <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput> -subscribe freebsd-announce -^D</screen> - - <para>If you want to subscribe yourself under a different name, or - submit a subscription request for a local mailing list (this is more - efficient if you have several interested parties at one site, and - highly appreciated by us!), you would do something like:</para> - - <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput> -subscribe freebsd-announce local-announce@somesite.com -^D</screen> - - <para>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:</para> - - <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput> -help -^D</screen> - - <para>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.</para> - </sect2> - - <sect2 id="eresources-charters"> - <title>List charters</title> - - <para><emphasis>All</emphasis>FreeBSD mailing lists have certain basic - rules which must be adhered to by anyone using them. Failure to comply - with these guidelines will result in two (2) written warnings from the - FreeBSD Postmaster <email>postmaster@FreeBSD.org</email>, after which, - on a third offense, the poster will removed from all FreeBSD mailing - lists and filtered from further posting to them. We regret that such - rules and measures are necessary at all, but today's Internet is a - pretty harsh environment, it would seem, and many fail to appreciate - just how fragile some of its mechanisms are.</para> - - <para>Rules of the road:</para> - - <itemizedlist> - <listitem> - <para>The topic of any posting should adhere to the basic charter of - the list it is posted to, e.g. if the list is about technical - issues then your posting should contain technical discussion. - Ongoing irrelevant chatter or flaming only detracts from the value - of the mailing list for everyone on it and will not be tolerated. - For free-form discussion on no particular topic, the freebsd-chat - <email>freebsd-chat@FreeBSD.org</email> mailing list is freely - available and should be used instead.</para> - </listitem> - - <listitem> - <para>No posting should be made to more than 2 mailing lists, and - only to 2 when a clear and obvious need to post to both lists - exists. For most lists, there is already a great deal of - subscriber overlap and except for the most esoteric mixes (say - "-stable & -scsi"), there really is no reason to post to more - than one list at a time. If a message is sent to you in such a - way that multiple mailing lists appear on the Cc line then the cc - line should also be trimmed before sending it out again. - <emphasis>You are <emphasis>still</emphasis> responsible for your - own cross-postings, no matter who the originator might have - been.</emphasis></para> - </listitem> - - <listitem> - <para>Personal attacks and profanity (in the context of an argument) - are not allowed, and that includes users and developers alike. - Gross breaches of netiquette, like excerpting or reposting private - mail when permission to do so was not and would not be - forthcoming, are frowned upon but not specifically enforced. - <emphasis>However</emphasis>, there are also very few cases where - such content would fit within the charter of a list and it would - therefore probably rate a warning (or ban) on that basis - alone.</para> - </listitem> - - <listitem> - <para>Advertising of non-FreeBSD related products or services is - strictly prohibited and will result in an immediate ban if it is - clear that the offender is advertising by spam.</para> - </listitem> - </itemizedlist> - - <para><emphasis>Individual list charters:</emphasis></para> - - <variablelist> - <varlistentry> - <term>FREEBSD-AFS</term> - - <listitem> - <para><emphasis>Andrew File System</emphasis></para> - - <para>This list is for discussion on porting and using AFS from - CMU/Transarc</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ADMIN</term> - - <listitem> - <para><emphasis>Administrative issues</emphasis></para> - - <para>This list is purely for discussion of <hostid - role="domainname">FreeBSD.org</hostid> related issues and to - report problems or abuse of project resources. It is a closed - list, though anyone may report a problem (with our systems!) to - it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ANNOUNCE</term> - - <listitem> - <para><emphasis>Important events / milestones</emphasis></para> - - <para>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, strictly - moderated mailing list.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ARCH</term> - - <listitem> - <para><emphasis>Architecture and design - discussions</emphasis></para> - - <para>This is a moderated list for discussion of FreeBSD - architecture. Messages will mostly be kept technical in nature, - with (rare) exceptions for other messages the moderator deems - need to reach all the subscribers of the list. Examples of - suitable topics;</para> - - <itemizedlist> - <listitem> - <para>How to re-vamp the build system to have several - customized builds running at the same time.</para> - </listitem> - - <listitem> - <para>What needs to be fixed with VFS to make Heidemann layers - work.</para> - </listitem> - - <listitem> - <para>How do we change the device driver interface to be able - to use the ame drivers cleanly on many buses and - architectures?</para> - </listitem> - - <listitem> - <para>How do I write a network driver?</para> - </listitem> - </itemizedlist> - - <para>The moderator reserves the right to do minor editing - (spell-checking, grammar correction, trimming) of messages that - are posted to the list. The volume of the list will be kept - low, which may involve having to delay topics until an active - discussion has been resolved.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-BUGS</term> - - <listitem> - <para><emphasis>Bug reports</emphasis></para> - - <para>This is the mailing list for reporting bugs in FreeBSD - Whenever possible, bugs should be submitted using the - &man.send-pr.1; - command or the <ulink - url="http://www.FreeBSD.org/send-pr.html">WEB - interface</ulink> to it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-CHAT</term> - - <listitem> - <para><emphasis>Non technical items related to the FreeBSD - community</emphasis></para> - - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-CORE</term> - - <listitem> - <para><emphasis>FreeBSD core team</emphasis></para> - - <para>This is an internal mailing list for use by the core - members. Messages can be sent to it when a serious - FreeBSD-related matter requires arbitration or high-level - scrutiny.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-CURRENT</term> - - <listitem> - <para><emphasis>Discussions about the use of - FreeBSD-current</emphasis></para> - - <para>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. This is a technical mailing list - for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-CURRENT-DIGEST</term> - - <listitem> - <para><emphasis>Discussions about the use of - FreeBSD-current</emphasis></para> - - <para>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. This list is - <emphasis>Read-Only</emphasis> and should not be posted - to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-DOC</term> - - <listitem> - <para><emphasis>Documentation project</emphasis></para> - - <para>This mailing list is for the discussion of issues and - projects related to the creation of documentation for FreeBSD. - The members of this mailing list are collectively referred to as - “The FreeBSD Documentation Project”. It is an open - list; feel free to join and contribute!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-FS</term> - - <listitem> - <para><emphasis>Filesystems</emphasis></para> - - <para>Discussions concerning FreeBSD filesystems. This is a - technical mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-IPFW</term> - - <listitem> - <para>IP Firewall</para> - - <para>This is the forum for technical discussions concerning the - redesign of the IP firewall code in FreeBSD. This is a - technical mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ISDN</term> - - <listitem> - <para><emphasis>ISDN Communications</emphasis></para> - - <para>This is the mailing list for people discussing the - development of ISDN support for FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-JAVA</term> - - <listitem> - <para><emphasis>Java Development</emphasis></para> - - <para>This is the mailing list for people discussing the - development of significant Java applications for FreeBSD and the - porting and maintenance of JDKs.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-HACKERS</term> - - <listitem> - <para><emphasis>Technical discussions</emphasis></para> - - <para>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. This is a - technical mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-HACKERS-DIGEST</term> - - <listitem> - <para><emphasis>Technical discussions</emphasis></para> - - <para>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. This list is - <emphasis>Read-Only</emphasis> and should not be posted - to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-HARDWARE</term> - - <listitem> - <para><emphasis>General discussion of FreeBSD - hardware</emphasis></para> - - <para>General discussion about the types of hardware that FreeBSD - runs on, various problems and suggestions concerning what to buy - or avoid.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-INSTALL</term> - - <listitem> - <para><emphasis>Installation discussion</emphasis></para> - - <para>This mailing list is for discussing FreeBSD installation - development for the future releases and is closed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ISP</term> - - <listitem> - <para><emphasis>Issues for Internet Service - Providers</emphasis></para> - - <para>This mailing list is for discussing topics relevant to - Internet Service Providers (ISPs) using FreeBSD. This is a - technical mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-NEWBIES</term> - - <listitem> - <para><emphasis>Newbies activities discussion</emphasis></para> - - <para>We cover any of the activities of newbies that are not - already dealt with elsewhere, including: independent learning - and problem solving techniques, finding and using resources and - asking for help elsewhere, how to use mailing lists and which - lists to use, general chat, making mistakes, boasting, sharing - ideas, stories, moral (but not technical) support, and taking an - active part in the FreeBSD community. We take our problems and - support questions to freebsd-questions, and use freebsd-newbies - to meet others who are doing the same things that we do as - newbies.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-PLATFORMS</term> - - <listitem> - <para><emphasis>Porting to Non-Intel platforms</emphasis></para> - - <para>Cross-platform FreeBSD issues, general discussion and - proposals for non-Intel FreeBSD ports. This is a technical - mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-POLICY</term> - - <listitem> - <para>Core team policy decisions</para> - - <para>This is a low volume, read-only mailing list for FreeBSD - Core Team Policy decisions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-PORTS</term> - - <listitem> - <para><emphasis>Discussion of - “ports”</emphasis></para> - - <para>Discussions concerning FreeBSD's “ports - collection” (<filename>/usr/ports</filename>), proposed - ports, modifications to ports collection infrastructure and - general coordination efforts. This is a technical mailing list - for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-QUESTIONS</term> - - <listitem> - <para><emphasis>User questions</emphasis></para> - - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-QUESTIONS-DIGEST</term> - - <listitem> - <para><emphasis>User questions</emphasis></para> - - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-SCSI</term> - - <listitem> - <para><emphasis>SCSI subsystem</emphasis></para> - - <para>This is the mailing list for people working on the scsi - subsystem for FreeBSD. This is a technical mailing list for - which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-SECURITY</term> - - <listitem> - <para><emphasis>Security issues</emphasis></para> - - <para>FreeBSD computer security issues (DES, Kerberos, known - security holes and fixes, etc). This is a technical mailing - list for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-SECURITY-NOTIFICATIONS</term> - - <listitem> - <para><emphasis>Security Notifications</emphasis> - Notifications of FreeBSD security problems and fixes. This is - not a discussion list. The discussion list is - FreeBSD-security.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-SMALL</term> - - <listitem> - <para>This list discusses topics related to unusually small and - embedded FreeBSD installations. This is a technical mailing - list for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-STABLE</term> - - <listitem> - <para><emphasis>Discussions about the use of - FreeBSD-stable</emphasis></para> - - <para>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. This is a technical mailing list - for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-USER-GROUPS</term> - - <listitem> - <para><emphasis>User Group Coordination List</emphasis></para> - - <para>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. It is a closed list.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="eresources-news"> - <title>Usenet newsgroups</title> - - <para>In addition to two FreeBSD specific newsgroups, there are many - others in which FreeBSD is discussed or are otherwise relevant to - FreeBSD users. <ulink - url="http://minnie.cs.adfa.edu.au/BSD-info/bsdnews_search.html">Keyword - searchable archives</ulink> are available for some of these newsgroups - from courtesy of Warren Toomey <email>wkt@cs.adfa.edu.au</email>.</para> - - <sect2> - <title>BSD specific newsgroups</title> - - <itemizedlist> - <listitem> - <para><ulink - url="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Other Unix newsgroups of interest</title> - - <itemizedlist> - <listitem> - <para><ulink url="news:comp.unix">comp.unix</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.questions">comp.unix.questions</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.admin">comp.unix.admin</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.programmer">comp.unix.programmer</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.shell">comp.unix.shell</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.user-friendly">comp.unix.user-friendly</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.security.unix">comp.security.unix</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.sources.unix">comp.sources.unix</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.advocacy">comp.unix.advocacy</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.misc">comp.unix.misc</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.bugs.4bsd">comp.bugs.4bsd</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.bugs.4bsd.ucb-fixes">comp.bugs.4bsd.ucb-fixes</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.bsd">comp.unix.bsd</ulink></para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>X Window System</title> - - <itemizedlist> - <listitem> - <para><ulink - url="news:comp.windows.x.i386unix">comp.windows.x.i386unix</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x">comp.windows.x</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.apps">comp.windows.x.apps</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.announce">comp.windows.x.announce</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.intrinsics">comp.windows.x.intrinsics</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.motif">comp.windows.x.motif</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.pex">comp.windows.x.pex</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine</ulink></para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="eresources-web"> - <title>World Wide Web servers</title> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.FreeBSD.org/">http://www.FreeBSD.org/</ulink> - — Central Server.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.au.FreeBSD.org/FreeBSD/">http://www.au.FreeBSD.org/FreeBSD/</ulink> — Australia/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.au.FreeBSD.org/FreeBSD/">http://www2.au.FreeBSD.org/FreeBSD/</ulink> — Australia/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.au.FreeBSD.org/FreeBSD/">http://www3.au.FreeBSD.org/FreeBSD/</ulink> — Australia/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.br.FreeBSD.org/www.FreeBSD.org/">http://www.br.FreeBSD.org/www.FreeBSD.org/</ulink> — Brazil/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.br.FreeBSD.org/www.FreeBSD.org/">http://www2.br.FreeBSD.org/www.FreeBSD.org/</ulink> — Brazil/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.br.FreeBSD.org/">http://www3.br.FreeBSD.org/</ulink> — Brazil/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.bg.FreeBSD.org/">http://www.bg.FreeBSD.org/</ulink> — Bulgaria.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ca.FreeBSD.org/">http://www.ca.FreeBSD.org/</ulink> — Canada/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://FreeBSD.kawartha.com/">http://FreeBSD.kawartha.com/</ulink> — Canada/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.dk.FreeBSD.org/">http://www.dk.FreeBSD.org/</ulink> — Denmark.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ee.FreeBSD.org/">http://www.ee.FreeBSD.org/</ulink> — Estonia.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.fi.FreeBSD.org/">http://www.fi.FreeBSD.org/</ulink> — Finland/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.fi.FreeBSD.org/">http://www2.fi.FreeBSD.org/</ulink> — Finland/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.fr.FreeBSD.org/">http://www.fr.FreeBSD.org/</ulink> — France.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.de.FreeBSD.org/">http://www.de.FreeBSD.org/</ulink> — Germany/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www1.de.FreeBSD.org/">http://www1.de.FreeBSD.org/</ulink> — Germany/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.de.FreeBSD.org/">http://www.de.FreeBSD.org/</ulink> — Germany/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.hu.FreeBSD.org/">http://www.hu.FreeBSD.org/</ulink> — Hungary.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.is.FreeBSD.org/">http://www.is.FreeBSD.org/</ulink> — Iceland.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ie.FreeBSD.org/">http://www.ie.FreeBSD.org/</ulink> — Ireland.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.jp.FreeBSD.org/www.FreeBSD.org/">http://www.jp.FreeBSD.org/www.FreeBSD.org/</ulink> — Japan.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.kr.FreeBSD.org/">http://www.kr.FreeBSD.org/</ulink> — Korea.</para> - </listitem> - - <listitem> - <para><ulink - url="http://rama.asiapac.net/freebsd/">http://rama.asiapac.net/freebsd/</ulink> — Malaysia.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.nl.FreeBSD.org/">http://www.nl.FreeBSD.org/</ulink> — Netherlands.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.no.FreeBSD.org/">http://www.no.FreeBSD.org/</ulink> — Norway.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.pt.FreeBSD.org/">http://www.pt.FreeBSD.org/</ulink> — Portugal/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.pt.FreeBSD.org/">http://www2.pt.FreeBSD.org/</ulink> — Portugal/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.pt.FreeBSD.org/">http://www3.pt.FreeBSD.org/</ulink> — Portugal/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ro.FreeBSD.org/">http://www.ro.FreeBSD.org/</ulink> — Romania.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ru.FreeBSD.org/">http://www.ru.FreeBSD.org/</ulink> — Russia/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.ru.FreeBSD.org/">http://www2.ru.FreeBSD.org/</ulink> — Russia/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.ru.FreeBSD.org/">http://www3.ru.FreeBSD.org/</ulink> — Russia/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www4.ru.FreeBSD.org/">http://www4.ru.FreeBSD.org/</ulink> — Russia/4.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.sk.FreeBSD.org/">http://www.sk.FreeBSD.org/</ulink> — Slovak Republic.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.si.FreeBSD.org/">http://www.si.FreeBSD.org/</ulink> — Slovenia.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.es.FreeBSD.org/">http://www.es.FreeBSD.org/</ulink> — Spain.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.za.FreeBSD.org/">http://www.za.FreeBSD.org/</ulink> — South Africa/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.za.FreeBSD.org/">http://www2.za.FreeBSD.org/</ulink> — South Africa/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.se.FreeBSD.org/www.FreeBSD.org/">http://www.se.FreeBSD.org/www.FreeBSD.org/</ulink> — Sweden.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.tr.FreeBSD.org/">http://www.tr.FreeBSD.org/</ulink> — Turkey.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ua.FreeBSD.org/">http://www.ua.FreeBSD.org/</ulink> — Ukraine/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.ua.FreeBSD.org/">http://www2.ua.FreeBSD.org/</ulink> — Ukraine/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.uk.FreeBSD.org/">http://www.uk.FreeBSD.org/</ulink> — United Kingdom.</para> - </listitem> - - <listitem> - <para><ulink - url="http://freebsd.advansys.net/">http://freebsd.advansys.net/</ulink> — USA/Indiana.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www6.FreeBSD.org/">http://www6.FreeBSD.org/</ulink> — USA/Oregon.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.FreeBSD.org/">http://www2.FreeBSD.org/</ulink> — USA/Texas.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="eresources-email"> - <title>Email Addresses</title> - - <para>The following user groups provide FreeBSD related email addresses - for their members. The listed administrator reserves the right to - revoke the address if it is abused in any way.</para> - - <informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Domain</entry> - <entry>Facilities</entry> - <entry>User Group</entry> - <entry>Administrator</entry> - </row> - </thead> - - <tbody> - <row> - <entry>ukug.uk.FreeBSD.org</entry> - <entry>Forwarding only</entry> - <entry><email>freebsd-users@uk.FreeBSD.org</email></entry> - <entry>Lee Johnston - <email>lee@uk.FreeBSD.org</email></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1 id="eresources-shell"> - <title>Shell Accounts</title> - - <para>The following user groups provide shell accounts for people who are - actively supporting the FreeBSD project. The listed administrator - reserves the right to cancel the account if it is abused in any - way.</para> - - <informaltable> - <tgroup cols="4"> - <thead> - <row> - <entry>Host</entry> - <entry>Access</entry> - <entry>Facilities</entry> - <entry>Administrator</entry> - </row> - </thead> - - <tbody> - <row> - <entry>storm.uk.FreeBSD.org</entry> - <entry>ssh only</entry> - <entry>Read-only cvs, personal webspace, email</entry> - <entry>&a.brian</entry> - </row> - - <row> - <entry>dogma.freebsd-uk.eu.org</entry> - <entry>Telnet/FTP/SSH</entry> - <entry>E-Mail, Webspace, Anonymous FTP</entry> - <entry>Lee Johnston - <email>lee@uk.FreeBSD.org</email></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/handbook.sgml b/en/handbook/handbook.sgml deleted file mode 100644 index 3c599ca076..0000000000 --- a/en/handbook/handbook.sgml +++ /dev/null @@ -1,129 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: handbook.sgml,v 1.78 1999-07-28 20:23:02 nik Exp $ ---> - -<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN"> -%bookinfo; - -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -<!ENTITY % authors SYSTEM "authors.ent"> %authors; -<!ENTITY % mailing-lists SYSTEM "mailing-lists.ent"> %mailing-lists; -<!ENTITY % newsgroups SYSTEM "newsgroups.ent"> %newsgroups; - -<!-- The currently released version of FreeBSD. This value is used to - create some links on web sites and such, so do NOT change it until - it's really release time --> -<!ENTITY rel.current CDATA "3.2"> -]> - -<book> - <bookinfo> - <title>FreeBSD Handbook</title> - - <authorgroup> - <author> - <surname>The FreeBSD Documentation Project</surname> - </author> - </authorgroup> - - <pubdate>February 1999</pubdate> - - <copyright> - <year>1995</year> - <year>1996</year> - <year>1997</year> - <year>1998</year> - <year>1999</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - &bookinfo.legalnotice; - - <abstract> - <para>Welcome to FreeBSD! This handbook covers the installation and day - to day use of <emphasis>FreeBSD Release &rel.current;</emphasis>. - This manual is a <emphasis>work in progress</emphasis> 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 <ulink - URL="http://www.FreeBSD.org/">FreeBSD World Wide Web server</ulink>. - It may also be downloaded in a variety of formats and compression - options from the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc">FreeBSD FTP - server</ulink> or one of the numerous <link - linkend="mirrors-ftp">mirror sites</link>. You may also want to - <ulink URL="http://www.FreeBSD.org/search.html">Search the - Handbook</ulink>.</para> - </abstract> - </bookinfo> - - <part> - <title>Getting Started</title> - - &chap.introduction; - &chap.install; - &chap.basics; - &chap.ports - </part> - - <part> - <title>System Administration</title> - - &chap.kernelconfig; - &chap.security; - &chap.printing; - &chap.disks; - &chap.backups; - &chap.quotas; - &chap.x11; - &chap.hw; - &chap.l10n; - </part> - - <part> - <title>Network Communications</title> - - &chap.serialcomms; - &chap.ppp-and-slip; - &chap.advanced-networking; - &chap.mail; - </part> - - <part> - <title>Advanced topics</title> - - &chap.cutting-edge; - &chap.contrib; - &chap.policies; - &chap.kernelopts; - &chap.kerneldebug; - &chap.linuxemu; - &chap.internals; - </part> - - <part> - <title>Appendices</title> - - &chap.mirrors; - &chap.bibliography; - &chap.eresources; - &chap.staff; - &chap.pgpkeys; - </part> -</book> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en/handbook/hw/chapter.sgml b/en/handbook/hw/chapter.sgml deleted file mode 100644 index 45e382b4ae..0000000000 --- a/en/handbook/hw/chapter.sgml +++ /dev/null @@ -1,5612 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.22 1999-08-11 22:28:16 nik Exp $ ---> - -<chapter id="hw"> - <title>PC Hardware compatibility</title> - - <para>Issues of hardware compatibility are among the most troublesome in the - computer industry today and FreeBSD is by no means immune to trouble. In - this respect, FreeBSD's advantage of being able to run on inexpensive - commodity PC hardware is also its liability when it comes to support for - the amazing variety of components on the market. While it would be - impossible to provide a exhaustive listing of hardware that FreeBSD - supports, this section serves as a catalog of the device drivers included - with FreeBSD and the hardware each drivers supports. Where possible and - appropriate, notes about specific products are included. You may also - want to refer to <link linkend="kernelconfig-config">the kernel - configuration file</link> section in this handbook for a list of - supported devices.</para> - - <para>As FreeBSD is a volunteer project without a funded testing department, - we depend on you, the user, for much of the information contained in this - catalog. If you have direct experience of hardware that does or does not - work with FreeBSD, please let us know by sending e-mail to the &a.doc;. - Questions about supported hardware should be directed to the &a.questions; - (see <link linkend="eresources-mail">Mailing Lists</link> for more - information). When submitting information or asking a question, please - remember to specify exactly what version of FreeBSD you are using and - include as many details of your hardware as possible.</para> - - <sect1> - <title>Resources on the Internet</title> - - <para>The following links have proven useful in selecting hardware. Though - some of what you see won't necessarily be specific (or even applicable) - to FreeBSD, most of the hardware information out there is OS - independent. Please check with the FreeBSD hardware guide to make sure - that your chosen configuration is supported before making any - purchases.</para> - - <itemizedlist> - <listitem> - <para><ulink URL="http://www.tomshardware.com/">The Pentium Systems - Hardware Performance Guide</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="hw-configs"> - <title>Sample Configurations</title> - - <para>The following list of sample hardware configurations by no means - constitutes an endorsement of a given hardware vendor or product by - <emphasis>The FreeBSD Project</emphasis>. This information is provided - only as a public service and merely catalogs some of the experiences - that various individuals have had with different hardware combinations. - Your mileage may vary. Slippery when wet. Beware of dog.</para> - - <sect2 id="hw-jordans-picks"> - <title>Jordan's Picks</title> - - <para>I have had fairly good luck building workstation and server - configurations with the following components. I can't guarantee that - you will too, nor that any of the companies here will remain - “best buys” forever. I will try, when I can, to keep this - list up-to-date but cannot obviously guarantee that it will be at any - given time.</para> - - <sect3 id="hw-mb"> - <title>Motherboards</title> - - <para>For Pentium Pro (P6) systems, I'm quite fond of the <ulink - URL="http://www.tyan.com/html/products.html">Tyan</ulink> S1668 - dual-processor motherboard as well as the Intel PR440FX motherboard - with on-board SCSI WIDE and 100/10MB Intel Etherexpress NIC. You - can build a dandy little single or dual processor system (which is - supported in FreeBSD 3.0) for very little cost now that the Pentium - Pro 180/256K chips have fallen so greatly in price, but no telling - how much longer this will last.</para> - - <para>For the Pentium II, I'm rather partial to the <ulink - URL="http://www.asus.com.tw">ASUS</ulink> <ulink - URL="http://www.asus.com.tw/Products/Motherboard/Pentiumpro/P2l97-s/index.html">P2l97-S</ulink> - motherboard with the on-board Adaptec SCSI WIDE controller.</para> - - <para>For Pentium machines, the ASUS <ulink - URL="http://www.asus.com.tw/Products/Motherboard/Pentium/P55tp4/index.html">P55T2P4</ulink> - motherboard appears to be a good choice for mid-to-high range - Pentium server and workstation systems.</para> - - <para>Those wishing to build more fault-tolerant systems should also - be sure to use Parity memory or, for truly 24/7 applications, ECC - memory.</para> - - <note> - <para>ECC memory does involve a slight performance trade-off (which - may or may not be noticeable depending on your application) but - buys you significantly increased fault-tolerance to memory - errors.</para> - </note> - </sect3> - - <sect3> - <title>Disk Controllers</title> - - <para>This one is a bit trickier, and while I used to recommend the - <ulink URL="http://www.buslogic.com">Buslogic</ulink> controllers - unilaterally for everything from ISA to PCI, now I tend to lean - towards the <ulink URL="http://www.adaptec.com">Adaptec</ulink> - 1542CF for ISA, Buslogic Bt747c for EISA and Adaptec 2940UW for - PCI.</para> - - <para>The NCR/Symbios cards for PCI have also worked well for me, - though you need to make sure that your motherboard supports the - BIOS-less model if you're using one of those (if your card has - nothing which looks even vaguely like a ROM chip on it, you've - probably got one which expects its BIOS to be on your - motherboard).</para> - - <para>If you should find that you need more than one SCSI controller - in a PCI machine, you may wish to consider conserving your scarce - PCI bus resources by buying the Adaptec 3940 card, which puts two - SCSI controllers (and internal busses) in a single slot.</para> - - <note> - <para>There are two types of 3940 on the market—the older - model with AIC 7880 chips on it, and the newer one with AIC 7895 - chips. The newer model requires <ulink - url="http://www.FreeBSD.org/pub/FreeBSD/development/cam/">CAM</ulink> - support which is not yet part of FreeBSD—you have to add it, - or install from one of the CAM binary snapshot release.</para> - </note> - </sect3> - - <sect3 id="hw-disks"> - <title>Disk drives</title> - - <para>In this particular game of Russian roulette, I'll make few - specific recommendations except to say “SCSI over IDE whenever - you can afford it.” Even in small desktop configurations, SCSI - often makes more sense since it allows you to easily migrate drives - from server to desktop as falling drive prices make it economical to - do so. If you have more than one machine to administer then think - of it not simply as storage, think of it as a food chain! For a - serious server configuration, there's not even any - argument—use SCSI equipment and good cables.</para> - </sect3> - - <sect3 id="hw-jordans-picks-cdrom"> - <title>CDROM drives</title> - - <para>My SCSI preferences extend to SCSI CDROM drives as well, and - while the <ulink URL="http://www.toshiba.com">Toshiba</ulink> drives - have always been favourites of mine (in whatever speed is hot that - week), I'm still fond of my good old <ulink - url="http://www.plextor.com">Plextor</ulink> PX-12CS drive. It's - only a 12 speed, but it's offered excellent performance and - reliability.</para> - - <para>Generally speaking, most SCSI CDROM drives I've seen have been - of pretty solid construction and you probably won't go wrong with an - HP or NEC SCSI CDROM drive either. SCSI CDROM prices also appear to - have dropped considerably in the last few months and are now quite - competitive with IDE CDROMs while remaining a technically superior - solution. I now see no reason whatsoever to settle for an IDE CDROM - drive if given a choice between the two.</para> - </sect3> - - <sect3 id="hw-worm"> - <title>CD Recordable (WORM) drives</title> - - <para>At the time of this writing, FreeBSD supports 3 types of CDR - drives (though I believe they all ultimately come from Phillips - anyway): The Phillips CDD 522 (Acts like a Plasmon), the PLASMON - RF4100 and the HP 6020i. I myself use the HP 6020i for burning - CDROMs (in 2.2 and alter releases—it does not work with - earlier releases of the SCSI code) and it works very well. See - <ulink - URL="file:/usr/share/examples/worm">/usr/share/examples/worm</ulink> - on your 2.2 system for example scripts used to created ISO9660 - filesystem images (with RockRidge extensions) and burn them onto an - HP6020i CDR.</para> - </sect3> - - <sect3 id="hw-tape"> - <title>Tape drives</title> - - <para>I've had pretty good luck with both <ulink - URL="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">8mm - drives</ulink> from <ulink - URL="http://www.exabyte.com">Exabyte</ulink> and <ulink - URL="http://www-dmo.external.hp.com:80/tape/_cpb0001.htm">4mm - (DAT)</ulink> drives from <ulink - URL="http://www.hp.com">HP</ulink>.</para> - - <para>For backup purposes, I'd have to give the higher recommendation - to the Exabyte due to the more robust nature (and higher storage - capacity) of 8mm tape.</para> - </sect3> - - <sect3 id="hw-video"> - <title>Video Cards</title> - - <para>If you can also afford to buy a commercial X server for - US$99 from <ulink URL="http://www.xig.com/">Xi Graphics, Inc. - (formerly X Inside, Inc)</ulink> then I can heartily recommend the - <ulink URL="http://www.matrox.com/">Matrox</ulink> <ulink - URL="http://www.matrox.com/mgaweb/brochure.htm">Millenium - II</ulink> card. Note that support for this card is also - excellent with the <ulink - URL="http://www.xfree86.org/">XFree86</ulink> server, which is now - at version 3.3.2.</para> - - <para>You also certainly can't go wrong with one of <ulink - URL="http://www.nine.com/">Number 9's</ulink> cards — their - S3 Vision 868 and 968 based cards (the 9FX series) also being quite - fast and very well supported by XFree86's S3 server. You can also - pick up their Revolution 3D cards very cheaply these days, - especially if you require a lot of video memory.</para> - </sect3> - - <sect3 id="hw-monitors"> - <title>Monitors</title> - - <para>I have had very good luck with the <ulink - URL="http://cons3.sel.sony.com/SEL/ccpg/display/ms17se2.html">Sony - Multiscan 17seII monitors</ulink>, as have I with the Viewsonic - offering in the same (Trinitron) tube. For larger than 17", all I - can recommend at the time of this writing is to not spend any less - than U.S. $2,000 for a 21" monitor or $1,700 for a 20" - monitor if that's what you really need. There are good monitors - available in the >=20" range and there are also cheap monitors in - the >=20" range. Unfortunately, very few are both cheap and - good!</para> - </sect3> - - <sect3 id="hw-networking"> - <title>Networking</title> - - <para>I can recommend the Intel EtherExpress Pro/100B card first and - foremost, followed by the <ulink - URL="http://www.smc.com/">SMC</ulink> Ultra 16 controller for any - ISA application and the SMC EtherPower or Compex ENET32 cards for - slightly cheaper PCI based networking. In general, any PCI NIC - based around DEC's DC21041 Ethernet controller chip, such as the - Znyx ZX342 or DEC DE435/450, will generally work quite well and can - frequently be found in 2-port and 4-port version (useful for - firewalls and routers), though the Pro/100MB card has the edge when - it comes to providing the best performance with lower - overhead.</para> - - <para>If what you're looking for is the cheapest possible solution - then almost any NE2000 clone will do a fine job for very little - cost.</para> - </sect3> - - <sect3 id="hw-serial"> - <title>Serial</title> - - <para>If you're looking for high-speed serial networking solutions, - then <ulink URL="http://www.dgii.com/">Digi International</ulink> - makes the <ulink - URL="http://www.dgii.com/prodprofiles/profiles-prices/digiprofiles/digispecs/sync570.html">SYNC/570</ulink> - series, with drivers now in FreeBSD-current. <ulink - URL="http://www.etinc.com">Emerging Technologies</ulink> also - manufactures a board with T1/E1 capabilities, using software they - provide. I have no direct experience using either product, - however.</para> - - <para>Multiport card options are somewhat more numerous, though it has - to be said that FreeBSD's support for <ulink - URL="http://www.cyclades.com/">Cyclades</ulink>'s products is - probably the tightest, primarily as a result of that company's - commitment to making sure that we are adequately supplied with - evaluation boards and technical specs. I've heard that the - Cyclom-16Ye offers the best price/performance, though I've not - checked the prices lately. Other multiport cards I've heard good - things about are the BOCA and AST cards, and <ulink - URL="http://www.stallion.com/">Stallion Technologies</ulink> - apparently offers an unofficial driver for their cards at <ulink - URL="ftp://ftp.stallion.com/drivers/unsupported/freebsd/stalbsd-0.0.4.tar.gz">this</ulink> - location.</para> - </sect3> - - <sect3 id="hw-audio"> - <title>Audio</title> - - <para>I currently use a <ulink URL="http://www.creaf.com/">Creative - Labs</ulink> AWE32 though just about anything from Creative Labs - will generally work these days. This is not to say that other types - of sound cards don't also work, simply that I have little experience - with them (I was a former GUS fan, but Gravis's soundcard situation - has been dire for some time).</para> - </sect3> - - <sect3 id="hw-vgrabbers"> - <title>Video</title> - - <para>For video capture, there are two good choices — any card - based on the Brooktree BT848 chip, such as the Hauppage or WinTV - boards, will work very nicely with FreeBSD. Another board which - works for me is the <ulink - URL="http://www.matrox.com/">Matrox</ulink> <ulink - URL="http://www.matrox.com/imgweb/meteor.htm">Meteor</ulink> card. - FreeBSD also supports the older video spigot card from Creative - Labs, but those are getting somewhat difficult to find. Note that - the Meteor frame grabber card <emphasis>will not work</emphasis> - with motherboards based on the 440FX chipset! See the <link - linkend="hw-mb">motherboard reference</link> section for details. - In such cases, it's better to go with a BT848 based board.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="hw-core"> - <title>Core/Processing</title> - - <sect2> - <title>Motherboards, busses, and chipsets</title> - - <sect3> - <title>* ISA</title> - - <para></para> - </sect3> - - <sect3> - <title>* EISA</title> - - <para></para> - </sect3> - - <sect3> - <title>* VLB</title> - - <para></para> - </sect3> - - <sect3 id="hw-mb-pci"> - <title>PCI</title> - - <para><emphasis>Contributed by &a.obrien; from postings by - &a.rgrimes;. 25 April 1995.</emphasis></para> - - <para><emphasis>Continuing updates by &a.jkh;.</emphasis> Last - update on <emphasis>26 August 1996.</emphasis></para> - - <para>Of the Intel PCI chip sets, the following list describes various - types of known-brokenness and the degree of breakage, listed from - worst to best.</para> - - <variablelist> - <varlistentry> - <term>Mercury:</term> - - <listitem> - <para>Cache coherency problems, especially if there are ISA bus - masters behind the ISA to PCI bridge chip. Hardware flaw, only - known work around is to turn the cache off.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Saturn-I <emphasis>(ie, 82424ZX at rev 0, 1 or - 2)</emphasis>:</term> - - <listitem> - <para>Write back cache coherency problems. Hardware flaw, only - known work around is to set the external cache to - write-through mode. Upgrade to Saturn-II.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Saturn-II <emphasis>(ie, 82424ZX at rev 3 or - 4)</emphasis>:</term> - - <listitem> - <para>Works fine, but many MB manufactures leave out the - external dirty bit SRAM needed for write back operation. Work - arounds are either run it in write through mode, or get the - dirty bit SRAM installed. (I have these for the ASUS - PCI/I-486SP3G rev 1.6 and later boards).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Neptune:</term> - - <listitem> - <para>Can not run more than 2 bus master devices. Admitted Intel - design flaw. Workarounds include do not run more than 2 bus - masters, special hardware design to replace the PCI bus - arbiter (appears on Intel Altair board and several other Intel - server group MB's). And of course Intel's official answer, - move to the Triton chip set, we “fixed it - there”.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Triton <emphasis>(ie, 430FX)</emphasis>:</term> - - <listitem> - <para>No known cache coherency or bus master problems, chip set - does not implement parity checking. Workaround for parity - issue. Use Triton-II based motherboards if you have the - choice.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Triton-II <emphasis>(ie, 430HX)</emphasis>:</term> - - <listitem> - <para>All reports on motherboards using this chipset have been - favorable so far. No known problems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Orion:</term> - - <listitem> - <para>Early versions of this chipset suffered from a PCI - write-posting bug which can cause noticeable performance - degradation in applications where large amounts of PCI bus - traffic is involved. B0 stepping or later revisions of the - chipset fixed this problem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink - URL="http://developer.intel.com/design/pcisets/desktop.htm#440FX">440FX</ulink>:</term> - - <listitem> - <para>This <ulink - URL="http://www.intel.com/procs/ppro/index.htm">Pentium - Pro</ulink> support chipset seems to work well, and does not - suffer from any of the early Orion chipset problems. It also - supports a wider variety of memory, including ECC and parity. - The only known problem with it is that the Matrox Meteor frame - grabber card doesn't like it.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - </sect2> - - <sect2> - <title>CPUs/FPUs</title> - - <para><emphasis>Contributed by &a.asami;. 26 December - 1997.</emphasis></para> - - <sect3> - <title>P6 class (Pentium Pro/Pentium II)</title> - - <para>Both the Pentium Pro and Pentium II work fine with FreeBSD. In - fact, our main ftp site <ulink - URL="ftp://ftp.FreeBSD.org/">ftp.FreeBSD.org</ulink> (also known - as "<filename>ftp.cdrom.com</filename>", world's largest ftp site) - runs FreeBSD on a Pentium Pro. <ulink - URL="ftp://ftp.cdrom.com/archive-info/wcarchive.txt">Configurations - details</ulink> are available for interested parties.</para> - </sect3> - - <sect3> - <title>Pentium class</title> - - <para>The Intel Pentium (P54C), Pentium MMX (P55C), AMD K6 and - Cyrix/IBM 6x86MX processors are all reported to work with FreeBSD. - I will not go into details of which processor is faster than what, - there are zillions of web sites on the Internet that tells you one - way or another. <!-- smiley --><emphasis>:)</emphasis></para> - - <note> - <para>Various CPUs have different voltage/cooling requirements. Make - sure your motherboard can supply the exact voltage needed by the - CPU. For instance, many recent MMX chips require split voltage - (e.g., 2.9V core, 3.3V I/O). Also, some AMD and Cyrix/IBM chips - run hotter than Intel chips. In that case, make sure you have - good heatsink/fans (you can get the list of certified parts from - their web pages).</para> - </note> - - <sect4> - <title>Clock speeds</title> - - <para><emphasis>Contributed by &a.rgrimes;. 1 October - 1996.</emphasis></para> - - <para><emphasis>Updated by &a.asami;. 27 December - 1997.</emphasis></para> - - <para>Pentium class machines use different clock speeds for the - various parts of the system. These being the speed of the CPU, - external memory bus, and the PCI bus. It is not always true that - a “faster” processor will make a system faster than a - “slower” one, due to the various clock speeds used. - Below is a table showing the differences:</para> - - <informaltable frame="none"> - <tgroup cols="4"> - <thead> - <row> - <entry>Rated CPU MHz</entry> - <entry>External Clock and Memory Bus MHz</entry> - <entry>External to Internal Clock Multiplier</entry> - <entry>PCI Bus Clock MHz</entry> - </row> - </thead> - - <tbody> - <row> - <entry>60</entry> - <entry>60</entry> - <entry>1.0</entry> - <entry>30</entry> - </row> - - <row> - <entry>66</entry> - <entry>66</entry> - <entry>1.0</entry> - <entry>33</entry> - </row> - - <row> - <entry>75</entry> - <entry>50</entry> - <entry>1.5</entry> - <entry>25</entry> - </row> - - <row> - <entry>90</entry> - <entry>60</entry> - <entry>1.5</entry> - <entry>30</entry> - </row> - - <row> - <entry>100</entry> - <entry>50</entry> - <entry>2</entry> - <entry>25</entry> - </row> - - <row> - <entry>100</entry> - <entry>66</entry> - <entry>1.5</entry> - <entry>33</entry> - </row> - - <row> - <entry>120</entry> - <entry>60</entry> - <entry>2</entry> - <entry>30</entry> - </row> - - <row> - <entry>133</entry> - <entry>66</entry> - <entry>2</entry> - <entry>33</entry> - </row> - - <row> - <entry>150</entry> - <entry>60</entry> - <entry>2.5</entry> - <entry>30 (Intel, AMD)</entry> - </row> - - <row> - <entry>150</entry> - <entry>75</entry> - <entry>2</entry> - <entry>37.5 (Cyrix/IBM 6x86MX)</entry> - </row> - - <row> - <entry>166</entry> - <entry>66</entry> - <entry>2.5</entry> - <entry>33</entry> - </row> - - <row> - <entry>180</entry> - <entry>60</entry> - <entry>3</entry> - <entry>30</entry> - </row> - - <row> - <entry>200</entry> - <entry>66</entry> - <entry>3</entry> - <entry>33</entry> - </row> - - <row> - <entry>233</entry> - <entry>66</entry> - <entry>3.5</entry> - <entry>33</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>66MHz may actually be 66.667MHz, but don't assume so.</para> - - <para>The Pentium 100 can be run at either 50MHz external clock - with a multiplier of 2 or at 66MHz and a multiplier of - 1.5.</para> - </note> - - <para>As can be seen the best parts to be using are the 100, 133, - 166, 200 and 233, with the exception that at a multiplier of 3 or - more the CPU starves for memory.</para> - </sect4> - - <sect4> - <title>The AMD K6 Bug</title> - - <para>In 1997, there have been reports of the AMD K6 seg faulting - during heavy compilation. That problem has been fixed in 3Q '97. - According to reports, K6 chips with date mark “9733” - or larger (i.e., manufactured in the 33rd week of '97 or later) do - not have this bug.</para> - </sect4> - </sect3> - - <sect3> - <title>* 486 class</title> - - <para></para> - </sect3> - - <sect3> - <title>* 386 class</title> - - <para></para> - </sect3> - - <sect3> - <title>286 class</title> - - <para>Sorry, FreeBSD does not run on 80286 machines. It is nearly - impossible to run today's large full-featured UNIXes on such - hardware.</para> - </sect3> - </sect2> - - <sect2> - <title>* Memory</title> - - <para>The minimum amount of memory you must have to install FreeBSD is 5 - MB. Once your system is up and running you can <link - linkend="kernelconfig-building">build a custom kernel</link> that - will use less memory. If you use the <filename>boot4.flp</filename> - you can get away with having only 4 MB.</para> - </sect2> - - <sect2> - <title>* BIOS</title> - - <para></para> - </sect2> - </sect1> - - <sect1 id="hw-io"> - <title>Input/Output Devices</title> - - <sect2> - <title>* Video cards</title> - - <para></para> - </sect2> - - <sect2> - <title>* Sound cards</title> - - <para></para> - </sect2> - - <sect2> - <title>Serial ports and multiport cards</title> - - <sect3 id="uart"> - <title>The UART: What it is and how it works</title> - - <para><emphasis>Copyright © 1996 &a.uhclem;, All Rights - Reserved. 13 January 1996.</emphasis></para> - - <para>The Universal Asynchronous Receiver/Transmitter (UART) - controller is the key component of the serial communications - subsystem of a computer. The UART takes bytes of data and transmits - the individual bits in a sequential fashion. At the destination, a - second UART re-assembles the bits into complete bytes.</para> - - <para>Serial transmission is commonly used with modems and for - non-networked communication between computers, terminals and other - devices.</para> - - <para>There are two primary forms of serial transmission: Synchronous - and Asynchronous. Depending on the modes that are supported by the - hardware, the name of the communication sub-system will usually - include a <literal>A</literal> if it supports Asynchronous - communications, and a <literal>S</literal> if it supports - Synchronous communications. Both forms are described below.</para> - - <para>Some common acronyms are: - - <blockquote> - <para>UART Universal Asynchronous - Receiver/Transmitter</para> - </blockquote> - - <blockquote> - <para>USART Universal Synchronous-Asynchronous - Receiver/Transmitter</para> - </blockquote></para> - - <sect4> - <title>Synchronous Serial Transmission</title> - - <para>Synchronous serial transmission requires that the sender and - receiver share a clock with one another, or that the sender - provide a strobe or other timing signal so that the receiver knows - when to “read” the next bit of the data. In most - forms of serial Synchronous communication, if there is no data - available at a given instant to transmit, a fill character must be - sent instead so that data is always being transmitted. - Synchronous communication is usually more efficient because only - data bits are transmitted between sender and receiver, and - synchronous communication can be more more costly if extra wiring - and circuits are required to share a clock signal between the - sender and receiver.</para> - - <para>A form of Synchronous transmission is used with printers and - fixed disk devices in that the data is sent on one set of wires - while a clock or strobe is sent on a different wire. Printers and - fixed disk devices are not normally serial devices because most - fixed disk interface standards send an entire word of data for - each clock or strobe signal by using a separate wire for each bit - of the word. In the PC industry, these are known as Parallel - devices.</para> - - <para>The standard serial communications hardware in the PC does not - support Synchronous operations. This mode is described here for - comparison purposes only.</para> - </sect4> - - <sect4> - <title>Asynchronous Serial Transmission</title> - - <para>Asynchronous transmission allows data to be transmitted - without the sender having to send a clock signal to the receiver. - Instead, the sender and receiver must agree on timing parameters - in advance and special bits are added to each word which are used - to synchronize the sending and receiving units.</para> - - <para>When a word is given to the UART for Asynchronous - transmissions, a bit called the "Start Bit" is added to the - beginning of each word that is to be transmitted. The Start Bit - is used to alert the receiver that a word of data is about to be - sent, and to force the clock in the receiver into synchronization - with the clock in the transmitter. These two clocks must be - accurate enough to not have the frequency drift by more than 10% - during the transmission of the remaining bits in the word. (This - requirement was set in the days of mechanical teleprinters and is - easily met by modern electronic equipment.)</para> - - <para>After the Start Bit, the individual bits of the word of data - are sent, with the Least Significant Bit (LSB) being sent first. - Each bit in the transmission is transmitted for exactly the same - amount of time as all of the other bits, and the receiver - “looks” at the wire at approximately halfway through - the period assigned to each bit to determine if the bit is a - <literal>1</literal> or a <literal>0</literal>. For example, if - it takes two seconds to send each bit, the receiver will examine - the signal to determine if it is a <literal>1</literal> or a - <literal>0</literal> after one second has passed, then it will - wait two seconds and then examine the value of the next bit, and - so on.</para> - - <para>The sender does not know when the receiver has - “looked” at the value of the bit. The sender only - knows when the clock says to begin transmitting the next bit of - the word.</para> - - <para>When the entire data word has been sent, the transmitter may - add a Parity Bit that the transmitter generates. The Parity Bit - may be used by the receiver to perform simple error checking. - Then at least one Stop Bit is sent by the transmitter.</para> - - <para>When the receiver has received all of the bits in the data - word, it may check for the Parity Bits (both sender and receiver - must agree on whether a Parity Bit is to be used), and then the - receiver looks for a Stop Bit. If the Stop Bit does not appear - when it is supposed to, the UART considers the entire word to be - garbled and will report a Framing Error to the host processor when - the data word is read. The usual cause of a Framing Error is that - the sender and receiver clocks were not running at the same speed, - or that the signal was interrupted.</para> - - <para>Regardless of whether the data was received correctly or not, - the UART automatically discards the Start, Parity and Stop bits. - If the sender and receiver are configured identically, these bits - are not passed to the host.</para> - - <para>If another word is ready for transmission, the Start Bit for - the new word can be sent as soon as the Stop Bit for the previous - word has been sent.</para> - - <para>Because asynchronous data is “self synchronizing”, - if there is no data to transmit, the transmission line can be - idle.</para> - </sect4> - - <sect4> - <title>Other UART Functions</title> - - <para>In addition to the basic job of converting data from parallel - to serial for transmission and from serial to parallel on - reception, a UART will usually provide additional circuits for - signals that can be used to indicate the state of the transmission - media, and to regulate the flow of data in the event that the - remote device is not prepared to accept more data. For example, - when the device connected to the UART is a modem, the modem may - report the presence of a carrier on the phone line while the - computer may be able to instruct the modem to reset itself or to - not take calls by asserting or deasserting one more more of these - extra signals. The function of each of these additional signals is - defined in the EIA RS232-C standard.</para> - </sect4> - - <sect4> - <title>The RS232-C and V.24 Standards</title> - - <para>In most computer systems, the UART is connected to circuitry - that generates signals that comply with the EIA RS232-C - specification. There is also a CCITT standard named V.24 that - mirrors the specifications included in RS232-C.</para> - - <sect5> - <title>RS232-C Bit Assignments (Marks and Spaces)</title> - - <para>In RS232-C, a value of <literal>1</literal> is called a - <literal>Mark</literal> and a value of <literal>0</literal> is - called a <literal>Space</literal>. When a communication line is - idle, the line is said to be “Marking”, or - transmitting continuous <literal>1</literal> values.</para> - - <para>The Start bit always has a value of <literal>0</literal> (a - Space). The Stop Bit always has a value of <literal>1</literal> - (a Mark). This means that there will always be a Mark (1) to - Space (0) transition on the line at the start of every word, - even when multiple word are transmitted back to back. This - guarantees that sender and receiver can resynchronize their - clocks regardless of the content of the data bits that are being - transmitted.</para> - - <para>The idle time between Stop and Start bits does not have to - be an exact multiple (including zero) of the bit rate of the - communication link, but most UARTs are designed this way for - simplicity.</para> - - <para>In RS232-C, the "Marking" signal (a <literal>1</literal>) is - represented by a voltage between -2 VDC and -12 VDC, and a - "Spacing" signal (a <literal>0</literal>) is represented by a - voltage between 0 and +12 VDC. The transmitter is supposed to - send +12 VDC or -12 VDC, and the receiver is supposed to allow - for some voltage loss in long cables. Some transmitters in low - power devices (like portable computers) sometimes use only +5 - VDC and -5 VDC, but these values are still acceptable to a - RS232-C receiver, provided that the cable lengths are - short.</para> - </sect5> - - <sect5> - <title>RS232-C Break Signal</title> - - <para>RS232-C also specifies a signal called a - <literal>Break</literal>, which is caused by sending continuous - Spacing values (no Start or Stop bits). When there is no - electricity present on the data circuit, the line is considered - to be sending <literal>Break</literal>.</para> - - <para>The <literal>Break</literal> signal must be of a duration - longer than the time it takes to send a complete byte plus - Start, Stop and Parity bits. Most UARTs can distinguish between - a Framing Error and a Break, but if the UART cannot do this, the - Framing Error detection can be used to identify Breaks.</para> - - <para>In the days of teleprinters, when numerous printers around - the country were wired in series (such as news services), any - unit could cause a <literal>Break</literal> by temporarily - opening the entire circuit so that no current flowed. This was - used to allow a location with urgent news to interrupt some - other location that was currently sending information.</para> - - <para>In modern systems there are two types of Break signals. If - the Break is longer than 1.6 seconds, it is considered a "Modem - Break", and some modems can be programmed to terminate the - conversation and go on-hook or enter the modems' command mode - when the modem detects this signal. If the Break is smaller - than 1.6 seconds, it signifies a Data Break and it is up to the - remote computer to respond to this signal. Sometimes this form - of Break is used as an Attention or Interrupt signal and - sometimes is accepted as a substitute for the ASCII CONTROL-C - character.</para> - - <para>Marks and Spaces are also equivalent to “Holes” - and “No Holes” in paper tape systems.</para> - - <note> - <para>Breaks cannot be generated from paper tape or from any - other byte value, since bytes are always sent with Start and - Stop bit. The UART is usually capable of generating the - continuous Spacing signal in response to a special command - from the host processor.</para> - </note> - </sect5> - - <sect5> - <title>RS232-C DTE and DCE Devices</title> - - <para>The RS232-C specification defines two types of equipment: - the Data Terminal Equipment (DTE) and the Data Carrier Equipment - (DCE). Usually, the DTE device is the terminal (or computer), - and the DCE is a modem. Across the phone line at the other end - of a conversation, the receiving modem is also a DCE device and - the computer that is connected to that modem is a DTE device. - The DCE device receives signals on the pins that the DTE device - transmits on, and vice versa.</para> - - <para>When two devices that are both DTE or both DCE must be - connected together without a modem or a similar media translater - between them, a NULL modem must be used. The NULL modem - electrically re-arranges the cabling so that the transmitter - output is connected to the receiver input on the other device, - and vice versa. Similar translations are performed on all of - the control signals so that each device will see what it thinks - are DCE (or DTE) signals from the other device.</para> - - <para>The number of signals generated by the DTE and DCE devices - are not symmetrical. The DTE device generates fewer signals for - the DCE device than the DTE device receives from the DCE.</para> - </sect5> - - <sect5> - <title>RS232-C Pin Assignments</title> - - <para>The EIA RS232-C specification (and the ITU equivalent, V.24) - calls for a twenty-five pin connector (usually a DB25) and - defines the purpose of most of the pins in that - connector.</para> - - <para>In the IBM Personal Computer and similar systems, a subset - of RS232-C signals are provided via nine pin connectors (DB9). - The signals that are not included on the PC connector deal - mainly with synchronous operation, and this transmission mode is - not supported by the UART that IBM selected for use in the IBM - PC.</para> - - <para>Depending on the computer manufacturer, a DB25, a DB9, or - both types of connector may be used for RS232-C communications. - (The IBM PC also uses a DB25 connector for the parallel printer - interface which causes some confusion.)</para> - - <para>Below is a table of the RS232-C signal assignments in the - DB25 and DB9 connectors.</para> - - <informaltable frame="none"> - <tgroup cols="7"> - <thead> - <row> - <entry>DB25 RS232-C Pin</entry> - <entry>DB9 IBM PC Pin</entry> - <entry>EIA Circuit Symbol</entry> - <entry>CCITT Circuit Symbol</entry> - <entry>Common Name</entry> - <entry>Signal Source</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>-</entry> - <entry>AA</entry> - <entry>101</entry> - <entry>PG/FG</entry> - <entry>-</entry> - <entry>Frame/Protective Ground</entry> - </row> - - <row> - <entry>2</entry> - <entry>3</entry> - <entry>BA</entry> - <entry>103</entry> - <entry>TD</entry> - <entry>DTE</entry> - <entry>Transmit Data</entry> - </row> - - <row> - <entry>3</entry> - <entry>2</entry> - <entry>BB</entry> - <entry>104</entry> - <entry>RD</entry> - <entry>DCE</entry> - <entry>Receive Data</entry> - </row> - - <row> - <entry>4</entry> - <entry>7</entry> - <entry>CA</entry> - <entry>105</entry> - <entry>RTS</entry> - <entry>DTE</entry> - <entry>Request to Send</entry> - </row> - - <row> - <entry>5</entry> - <entry>8</entry> - <entry>CB</entry> - <entry>106</entry> - <entry>CTS</entry> - <entry>DCE</entry> - <entry>Clear to Send</entry> - </row> - - <row> - <entry>6</entry> - <entry>6</entry> - <entry>CC</entry> - <entry>107</entry> - <entry>DSR</entry> - <entry>DCE</entry> - <entry>Data Set Ready</entry> - </row> - - <row> - <entry>7</entry> - <entry>5</entry> - <entry>AV</entry> - <entry>102</entry> - <entry>SG/GND</entry> - <entry>-</entry> - <entry>Signal Ground</entry> - </row> - - <row> - <entry>8</entry> - <entry>1</entry> - <entry>CF</entry> - <entry>109</entry> - <entry>DCD/CD</entry> - <entry>DCE</entry> - <entry>Data Carrier Detect</entry> - </row> - - <row> - <entry>9</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>10</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>11</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>12</entry> - <entry>-</entry> - <entry>CI</entry> - <entry>122</entry> - <entry>SRLSD</entry> - <entry>DCE</entry> - <entry>Sec. Recv. Line Signal Detector</entry> - </row> - - <row> - <entry>13</entry> - <entry>-</entry> - <entry>SCB</entry> - <entry>121</entry> - <entry>SCTS</entry> - <entry>DCE</entry> - <entry>Secondary Clear to Send</entry> - </row> - - <row> - <entry>14</entry> - <entry>-</entry> - <entry>SBA</entry> - <entry>118</entry> - <entry>STD</entry> - <entry>DTE</entry> - <entry>Secondary Transmit Data</entry> - </row> - - <row> - <entry>15</entry> - <entry>-</entry> - <entry>DB</entry> - <entry>114</entry> - <entry>TSET</entry> - <entry>DCE</entry> - <entry>Trans. Sig. Element Timing</entry> - </row> - - <row> - <entry>16</entry> - <entry>-</entry> - <entry>SBB</entry> - <entry>119</entry> - <entry>SRD</entry> - <entry>DCE</entry> - <entry>Secondary Received Data</entry> - </row> - - <row> - <entry>17</entry> - <entry>-</entry> - <entry>DD</entry> - <entry>115</entry> - <entry>RSET</entry> - <entry>DCE</entry> - <entry>Receiver Signal Element Timing</entry> - </row> - - <row> - <entry>18</entry> - <entry>-</entry> - <entry>-</entry> - <entry>141</entry> - <entry>LOOP</entry> - <entry>DTE</entry> - <entry>Local Loopback</entry> - </row> - - <row> - <entry>19</entry> - <entry>-</entry> - <entry>SCA</entry> - <entry>120</entry> - <entry>SRS</entry> - <entry>DTE</entry> - <entry>Secondary Request to Send</entry> - </row> - - <row> - <entry>20</entry> - <entry>4</entry> - <entry>CD</entry> - <entry>108.2</entry> - <entry>DTR</entry> - <entry>DTE</entry> - <entry>Data Terminal Ready</entry> - </row> - - <row> - <entry>21</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>RDL</entry> - <entry>DTE</entry> - <entry>Remote Digital Loopback</entry> - </row> - - <row> - <entry>22</entry> - <entry>9</entry> - <entry>CE</entry> - <entry>125</entry> - <entry>RI</entry> - <entry>DCE</entry> - <entry>Ring Indicator</entry> - </row> - - <row> - <entry>23</entry> - <entry>-</entry> - <entry>CH</entry> - <entry>111</entry> - <entry>DSRS</entry> - <entry>DTE</entry> - <entry>Data Signal Rate Selector</entry> - </row> - - <row> - <entry>24</entry> - <entry>-</entry> - <entry>DA</entry> - <entry>113</entry> - <entry>TSET</entry> - <entry>DTE</entry> - <entry>Trans. Sig. Element Timing</entry> - </row> - - <row> - <entry>25</entry> - <entry>-</entry> - <entry>-</entry> - <entry>142</entry> - <entry>-</entry> - <entry>DCE</entry> - <entry>Test Mode</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect5> - </sect4> - - <sect4> - <title>Bits, Baud and Symbols</title> - - <para>Baud is a measurement of transmission speed in asynchronous - communication. Because of advances in modem communication - technology, this term is frequently misused when describing the - data rates in newer devices.</para> - - <para>Traditionally, a Baud Rate represents the number of bits that - are actually being sent over the media, not the amount of data - that is actually moved from one DTE device to the other. The Baud - count includes the overhead bits Start, Stop and Parity that are - generated by the sending UART and removed by the receiving UART. - This means that seven-bit words of data actually take 10 bits to - be completely transmitted. Therefore, a modem capable of moving - 300 bits per second from one place to another can normally only - move 30 7-bit words if Parity is used and one Start and Stop bit - are present.</para> - - <para>If 8-bit data words are used and Parity bits are also used, - the data rate falls to 27.27 words per second, because it now - takes 11 bits to send the eight-bit words, and the modem still - only sends 300 bits per second.</para> - - <para>The formula for converting bytes per second into a baud rate - and vice versa was simple until error-correcting modems came - along. These modems receive the serial stream of bits from the - UART in the host computer (even when internal modems are used the - data is still frequently serialized) and converts the bits back - into bytes. These bytes are then combined into packets and sent - over the phone line using a Synchronous transmission method. This - means that the Stop, Start, and Parity bits added by the UART in - the DTE (the computer) were removed by the modem before - transmission by the sending modem. When these bytes are received - by the remote modem, the remote modem adds Start, Stop and Parity - bits to the words, converts them to a serial format and then sends - them to the receiving UART in the remote computer, who then strips - the Start, Stop and Parity bits.</para> - - <para>The reason all these extra conversions are done is so that the - two modems can perform error correction, which means that the - receiving modem is able to ask the sending modem to resend a block - of data that was not received with the correct checksum. This - checking is handled by the modems, and the DTE devices are usually - unaware that the process is occurring.</para> - - <para>By striping the Start, Stop and Parity bits, the additional - bits of data that the two modems must share between themselves to - perform error-correction are mostly concealed from the effective - transmission rate seen by the sending and receiving DTE equipment. - For example, if a modem sends ten 7-bit words to another modem - without including the Start, Stop and Parity bits, the sending - modem will be able to add 30 bits of its own information that the - receiving modem can use to do error-correction without impacting - the transmission speed of the real data.</para> - - <para>The use of the term Baud is further confused by modems that - perform compression. A single 8-bit word passed over the - telephone line might represent a dozen words that were transmitted - to the sending modem. The receiving modem will expand the data - back to its original content and pass that data to the receiving - DTE.</para> - - <para>Modern modems also include buffers that allow the rate that - bits move across the phone line (DCE to DCE) to be a different - speed than the speed that the bits move between the DTE and DCE on - both ends of the conversation. Normally the speed between the DTE - and DCE is higher than the DCE to DCE speed because of the use of - compression by the modems.</para> - - <para>Because the number of bits needed to describe a byte varied - during the trip between the two machines plus the differing - bits-per-seconds speeds that are used present on the DTE-DCE and - DCE-DCE links, the usage of the term Baud to describe the overall - communication speed causes problems and can misrepresent the true - transmission speed. So Bits Per Second (bps) is the correct term - to use to describe the transmission rate seen at the DCE to DCE - interface and Baud or Bits Per Second are acceptable terms to use - when a connection is made between two systems with a wired - connection, or if a modem is in use that is not performing - error-correction or compression.</para> - - <para>Modern high speed modems (2400, 9600, 14,400, and 19,200bps) - in reality still operate at or below 2400 baud, or more - accurately, 2400 Symbols per second. High speed modem are able to - encode more bits of data into each Symbol using a technique called - Constellation Stuffing, which is why the effective bits per second - rate of the modem is higher, but the modem continues to operate - within the limited audio bandwidth that the telephone system - provides. Modems operating at 28,800 and higher speeds have - variable Symbol rates, but the technique is the same.</para> - </sect4> - - <sect4> - <title>The IBM Personal Computer UART</title> - - <para>Starting with the original IBM Personal Computer, IBM selected - the National Semiconductor INS8250 UART for use in the IBM PC - Parallel/Serial Adapter. Subsequent generations of compatible - computers from IBM and other vendors continued to use the INS8250 - or improved versions of the National Semiconductor UART - family.</para> - - <sect5> - <title>National Semiconductor UART Family Tree</title> - - <para>There have been several versions and subsequent generations - of the INS8250 UART. Each major version is described - below.</para> - - <!-- This should really be a graphic --> - <programlisting> -INS8250 -> INS8250B - \ - \ - \-> INS8250A -> INS82C50A - \ - \ - \-> NS16450 -> NS16C450 - \ - \ - \-> NS16550 -> NS16550A -> PC16550D</programlisting> - - <variablelist> - <varlistentry> - <term>INS8250</term> - - <listitem> - <para>This part was used in the original IBM PC and IBM - PC/XT. The original name for this part was the INS8250 - ACE (Asynchronous Communications Element) and it is made - from NMOS technology.</para> - - <para>The 8250 uses eight I/O ports and has a one-byte send - and a one-byte receive buffer. This original UART has - several race conditions and other flaws. The original IBM - BIOS includes code to work around these flaws, but this - made the BIOS dependent on the flaws being present, so - subsequent parts like the 8250A, 16450 or 16550 could not - be used in the original IBM PC or IBM PC/XT.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS8250-B</term> - - <listitem> - <para>This is the slower speed of the INS8250 made from NMOS - technology. It contains the same problems as the original - INS8250.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS8250A</term> - - <listitem> - <para>An improved version of the INS8250 using XMOS - technology with various functional flaws corrected. The - INS8250A was used initially in PC clone computers by - vendors who used “clean” BIOS designs. Because - of the corrections in the chip, this part could not be - used with a BIOS compatible with the INS8250 or - INS8250B.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS82C50A</term> - - <listitem> - <para>This is a CMOS version (low power consumption) of the - INS8250A and has similar functional - characteristics.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16450</term> - - <listitem> - <para>Same as NS8250A with improvements so it can be used - with faster CPU bus designs. IBM used this part in the - IBM AT and updated the IBM BIOS to no longer rely on the - bugs in the INS8250.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16C450</term> - - <listitem> - <para>This is a CMOS version (low power consumption) of the - NS16450.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16550</term> - - <listitem> - <para>Same as NS16450 with a 16-byte send and receive buffer - but the buffer design was flawed and could not be reliably - be used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16550A</term> - - <listitem> - <para>Same as NS16550 with the buffer flaws corrected. The - 16550A and its successors have become the most popular - UART design in the PC industry, mainly due it its ability - to reliably handle higher data rates on operating systems - with sluggish interrupt response times.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16C552</term> - - <listitem> - <para>This component consists of two NS16C550A CMOS UARTs in - a single package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>PC16550D</term> - - <listitem> - <para>Same as NS16550A with subtle flaws corrected. This is - revision D of the 16550 family and is the latest design - available from National Semiconductor.</para> - </listitem> - </varlistentry> - </variablelist> - </sect5> - - <sect5> - <title>The NS16550AF and the PC16550D are the same thing</title> - - <para>National reorganized their part numbering system a few years - ago, and the NS16550AFN no longer exists by that name. (If you - have a NS16550AFN, look at the date code on the part, which is a - four digit number that usually starts with a nine. The first - two digits of the number are the year, and the last two digits - are the week in that year when the part was packaged. If you - have a NS16550AFN, it is probably a few years old.)</para> - - <para>The new numbers are like PC16550DV, with minor differences - in the suffix letters depending on the package material and its - shape. (A description of the numbering system can be found - below.)</para> - - <para>It is important to understand that in some stores, you may - pay $15(US) for a NS16550AFN made in 1990 and in the next - bin are the new PC16550DN parts with minor fixes that National - has made since the AFN part was in production, the PC16550DN was - probably made in the past six months and it costs half (as low - as $5(US) in volume) as much as the NS16550AFN because they - are readily available.</para> - - <para>As the supply of NS16550AFN chips continues to shrink, the - price will probably continue to increase until more people - discover and accept that the PC16550DN really has the same - function as the old part number.</para> - </sect5> - - <sect5> - <title>National Semiconductor Part Numbering System</title> - - <para>The older NS<replaceable>nnnnnrqp</replaceable> part - numbers are now of the format - PC<replaceable>nnnnnrgp</replaceable>.</para> - - <para>The <replaceable>r</replaceable> is the revision field. The - current revision of the 16550 from National Semiconductor is - <literal>D</literal>.</para> - - <para>The <replaceable>p</replaceable> is the package-type field. - The types are:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>"F"</entry> - <entry>QFP</entry> - <entry>(quad flat pack) L lead type</entry> - </row> - - <row> - <entry>"N"</entry> - <entry>DIP</entry> - <entry>(dual inline package) through hole straight lead - type</entry> - </row> - - <row> - <entry>"V"</entry> - <entry>LPCC</entry> - <entry>(lead plastic chip carrier) J lead type</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>The <replaceable>g</replaceable> is the product grade field. - If an <literal>I</literal> precedes the package-type letter, it - indicates an “industrial” grade part, which has - higher specs than a standard part but not as high as Military - Specification (Milspec) component. This is an optional - field.</para> - - <para>So what we used to call a NS16550AFN (DIP Package) is now - called a PC16550DN or PC16550DIN.</para> - </sect5> - </sect4> - - <sect4> - <title>Other Vendors and Similar UARTs</title> - - <para>Over the years, the 8250, 8250A, 16450 and 16550 have been - licensed or copied by other chip vendors. In the case of the - 8250, 8250A and 16450, the exact circuit (the - “megacell”) was licensed to many vendors, including - Western Digital and Intel. Other vendors reverse-engineered the - part or produced emulations that had similar behavior.</para> - - <para>In internal modems, the modem designer will frequently emulate - the 8250A/16450 with the modem microprocessor, and the emulated - UART will frequently have a hidden buffer consisting of several - hundred bytes. Because of the size of the buffer, these - emulations can be as reliable as a 16550A in their ability to - handle high speed data. However, most operating systems will - still report that the UART is only a 8250A or 16450, and may not - make effective use of the extra buffering present in the emulated - UART unless special drivers are used.</para> - - <para>Some modem makers are driven by market forces to abandon a - design that has hundreds of bytes of buffer and instead use a - 16550A UART so that the product will compare favorably in market - comparisons even though the effective performance may be lowered - by this action.</para> - - <para>A common misconception is that all parts with - “16550A” written on them are identical in performance. - There are differences, and in some cases, outright flaws in most - of these 16550A clones.</para> - - <para>When the NS16550 was developed, the National Semiconductor - obtained several patents on the design and they also limited - licensing, making it harder for other vendors to provide a chip - with similar features. Because of the patents, reverse-engineered - designs and emulations had to avoid infringing the claims covered - by the patents. Subsequently, these copies almost never perform - exactly the same as the NS16550A or PC16550D, which are the parts - most computer and modem makers want to buy but are sometimes - unwilling to pay the price required to get the genuine - part.</para> - - <para>Some of the differences in the clone 16550A parts are - unimportant, while others can prevent the device from being used - at all with a given operating system or driver. These differences - may show up when using other drivers, or when particular - combinations of events occur that were not well tested or - considered in the Windows driver. This is because most modem - vendors and 16550-clone makers use the Microsoft drivers from - Windows for Workgroups 3.11 and the Microsoft MSD utility as the - primary tests for compatibility with the NS16550A. This - over-simplistic criteria means that if a different operating - system is used, problems could appear due to subtle differences - between the clones and genuine components.</para> - - <para>National Semiconductor has made available a program named - <application>COMTEST</application> that performs compatibility - tests independent of any OS drivers. It should be remembered that - the purpose of this type of program is to demonstrate the flaws in - the products of the competition, so the program will report major - as well as extremely subtle differences in behavior in the part - being tested.</para> - - <para>In a series of tests performed by the author of this document - in 1994, components made by National Semiconductor, TI, StarTech, - and CMD as well as megacells and emulations embedded in internal - modems were tested with COMTEST. A difference count for some of - these components is listed below. Because these tests were - performed in 1994, they may not reflect the current performance of - the given product from a vendor.</para> - - <para>It should be noted that COMTEST normally aborts when an - excessive number or certain types of problems have been detected. - As part of this testing, COMTEST was modified so that it would not - abort no matter how many differences were encountered.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>Vendor</entry> - <entry>Part Number</entry> - <entry>Errors (aka "differences" reported)</entry> - </row> - </thead> - - <tbody> - <row> - <entry>National</entry> - <entry>(PC16550DV)</entry> - <entry>0</entry> - </row> - - <row> - <entry>National</entry> - <entry>(NS16550AFN)</entry> - <entry>0</entry> - </row> - - <row> - <entry>National</entry> - <entry>(NS16C552V)</entry> - <entry>0</entry> - </row> - - <row> - <entry>TI</entry> - <entry>(TL16550AFN)</entry> - <entry>3</entry> - </row> - - <row> - <entry>CMD</entry> - <entry>(16C550PE)</entry> - <entry>19</entry> - </row> - - <row> - <entry>StarTech</entry> - <entry>(ST16C550J)</entry> - <entry>23</entry> - </row> - - <row> - <entry>Rockwell</entry> - <entry>Reference modem with internal 16550 or an - emulation (RC144DPi/C3000-25)</entry> - <entry>117</entry> - </row> - - <row> - <entry>Sierra</entry> - <entry>Modem with an internal 16550 - (SC11951/SC11351)</entry> - <entry>91</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>To date, the author of this document has not found any - non-National parts that report zero differences using the - COMTEST program. It should also be noted that National has had - five versions of the 16550 over the years and the newest parts - behave a bit differently than the classic NS16550AFN that is - considered the benchmark for functionality. COMTEST appears to - turn a blind eye to the differences within the National product - line and reports no errors on the National parts (except for the - original 16550) even when there are official erratas that - describe bugs in the A, B and C revisions of the parts, so this - bias in COMTEST must be taken into account.</para> - </note> - - <para>It is important to understand that a simple count of - differences from COMTEST does not reveal a lot about what - differences are important and which are not. For example, about - half of the differences reported in the two modems listed above - that have internal UARTs were caused by the clone UARTs not - supporting five- and six-bit character modes. The real 16550, - 16450, and 8250 UARTs all support these modes and COMTEST checks - the functionality of these modes so over fifty differences are - reported. However, almost no modern modem supports five- or - six-bit characters, particularly those with error-correction and - compression capabilities. This means that the differences related - to five- and six-bit character modes can be discounted.</para> - - <para>Many of the differences COMTEST reports have to do with - timing. In many of the clone designs, when the host reads from - one port, the status bits in some other port may not update in the - same amount of time (some faster, some slower) as a - <emphasis>real</emphasis> NS16550AFN and COMTEST looks for these - differences. This means that the number of differences can be - misleading in that one device may only have one or two differences - but they are extremely serious, and some other device that updates - the status registers faster or slower than the reference part - (that would probably never affect the operation of a properly - written driver) could have dozens of differences reported.</para> - - <para>COMTEST can be used as a screening tool to alert the - administrator to the presence of potentially incompatible - components that might cause problems or have to be handled as a - special case.</para> - - <para>If you run COMTEST on a 16550 that is in a modem or a modem is - attached to the serial port, you need to first issue a ATE0&W - command to the modem so that the modem will not echo any of the - test characters. If you forget to do this, COMTEST will report at - least this one difference:</para> - - <screen>Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61</screen> - </sect4> - - <sect4> - <title>8250/16450/16550 Registers</title> - - <para>The 8250/16450/16550 UART occupies eight contiguous I/O port - addresses. In the IBM PC, there are two defined locations for - these eight ports and they are known collectively as COM1 and - COM2. The makers of PC-clones and add-on cards have created two - additional areas known as COM3 and COM4, but these extra COM ports - conflict with other hardware on some systems. The most common - conflict is with video adapters that provide IBM 8514 - emulation.</para> - - <para>COM1 is located from 0x3f8 to 0x3ff and normally uses IRQ 4 - COM2 is located from 0x2f8 to 0x2ff and normally uses IRQ 3 COM3 - is located from 0x3e8 to 0x3ef and has no standardized IRQ COM4 is - located from 0x2e8 to 0x2ef and has no standardized IRQ.</para> - - <para>A description of the I/O ports of the 8250/16450/16550 UART is - provided below.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>I/O Port</entry> - <entry>Access Allowed</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>+0x00</entry> - <entry>write (DLAB==0)</entry> - <entry><para>Transmit Holding Register - (THR).</para><para>Information written to this port are - treated as data words and will be transmitted by the - UART.</para></entry> - </row> - - <row> - <entry>+0x00</entry> - <entry>read (DLAB==0)</entry> - <entry><para>Receive Buffer Register (RBR).</para><para>Any - data words received by the UART form the serial link are - accessed by the host by reading this - port.</para></entry> - </row> - - <row> - <entry>+0x00</entry> - <entry>write/read (DLAB==1)</entry> - <entry><para>Divisor Latch LSB (DLL)</para><para>This value - will be divided from the master input clock (in the IBM - PC, the master clock is 1.8432MHz) and the resulting - clock will determine the baud rate of the UART. This - register holds bits 0 thru 7 of the - divisor.</para></entry> - </row> - - <row> - <entry>+0x01</entry> - <entry>write/read (DLAB==1)</entry> - <entry><para>Divisor Latch MSB (DLH)</para><para>This value - will be divided from the master input clock (in the IBM - PC, the master clock is 1.8432MHz) and the resulting - clock will determine the baud rate of the UART. This - register holds bits 8 thru 15 of the - divisor.</para></entry> - </row> - - <row> - <entry>+0x01</entry> - <entry>write/read (DLAB==0)</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2"><para>Interrupt Enable Register - (IER)</para><para>The 8250/16450/16550 UART - classifies events into one of four categories. - Each category can be configured to generate an - interrupt when any of the events occurs. The - 8250/16450/16550 UART generates a single external - interrupt signal regardless of how many events in - the enabled categories have occurred. It is up to - the host processor to respond to the interrupt and - then poll the enabled interrupt categories - (usually all categories have interrupts enabled) - to determine the true cause(s) of the - interrupt.</para></entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Enable Modem Status Interrupt (EDSSI). Setting - this bit to "1" allows the UART to generate an - interrupt when a change occurs on one or more of the - status lines.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Enable Receiver Line Status Interrupt (ELSI) - Setting this bit to "1" causes the UART to generate - an interrupt when the an error (or a BREAK signal) - has been detected in the incoming data.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Enable Transmitter Holding Register Empty - Interrupt (ETBEI) Setting this bit to "1" causes the - UART to generate an interrupt when the UART has room - for one or more additional characters that are to be - transmitted.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Enable Received Data Available Interrupt - (ERBFI) Setting this bit to "1" causes the UART to - generate an interrupt when the UART has received - enough characters to exceed the trigger level of the - FIFO, or the FIFO timer has expired (stale data), or - a single character has been received when the FIFO - is disabled.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x02</entry> - <entry>write</entry> - <entrytbl cols="4"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <spanspec namest="col1" nameend="col4" spanname="1to4"> - <spanspec namest="col2" nameend="col4" spanname="2to4"> - - <tbody> - <row> - <entry spanname="1to4">FIFO Control Register (FCR) - (This port does not exist on the 8250 and 16450 - UART.)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to4">Receiver Trigger Bit #1</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to4"><para>Receiver Trigger Bit - #0</para><para>These two bits control at what - point the receiver is to generate an interrupt - when the FIFO is active.</para></entry> - </row> - - <row> - <entry colname="col2">7</entry> - <entry colname="col3">6</entry> - <entry colname="col4">How many words are received - before an interrupt is generated</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">1</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">4</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4">8</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4">14</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to4">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to4">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to4">DMA Mode Select. If Bit 0 is - set to "1" (FIFOs enabled), setting this bit changes - the operation of the -RXRDY and -TXRDY signals from - Mode 0 to Mode 1.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to4">Transmit FIFO Reset. When a - "1" is written to this bit, the contents of the FIFO - are discarded. Any word currently being transmitted - will be sent intact. This function is useful in - aborting transfers.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to4">Receiver FIFO Reset. When a - "1" is written to this bit, the contents of the FIFO - are discarded. Any word currently being assembled - in the shift register will be received - intact.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to4">16550 FIFO Enable. When set, - both the transmit and receive FIFOs are enabled. - Any contents in the holding register, shift - registers or FIFOs are lost when FIFOs are enabled - or disabled.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x02</entry> - <entry>read</entry> - <entrytbl cols="6"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <colspec colnum="5" colname="col5"> - <colspec colnum="6" colname="col6"> - <spanspec namest="col1" nameend="col6" spanname="1to6"> - <spanspec namest="col2" nameend="col6" spanname="2to6"> - - <tbody> - <row> - <entry spanname="1to6">Interrupt Identification - Register</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to6">FIFOs enabled. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to6">FIFOs enabled. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to6">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to6">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to6">Interrupt ID Bit #2. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to6">Interrupt ID Bit #1</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to6">Interrupt ID Bit #0.These three - bits combine to report the category of event that - caused the interrupt that is in progress. These - categories have priorities, so if multiple - categories of events occur at the same time, the - UART will report the more important events first and - the host must resolve the events in the order they - are reported. All events that caused the current - interrupt must be resolved before any new interrupts - will be generated. (This is a limitation of the PC - architecture.)</entry> - </row> - - <row> - <entry colname="col2">2</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Priority</entry> - <entry colname="col6">Description</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">1</entry> - <entry colname="col5">First</entry> - <entry colname="col6">Received Error (OE, PE, BI, or - FE)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Second</entry> - <entry colname="col6">Received Data Available</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Second</entry> - <entry colname="col6">Trigger level identification - (Stale data in receive buffer)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">1</entry> - <entry colname="col5">Third</entry> - <entry colname="col6">Transmitter has room for more - words (THRE)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Fourth</entry> - <entry colname="col6">Modem Status Change (-CTS, -DSR, - -RI, or -DCD)</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to6">Interrupt Pending Bit. If this - bit is set to "0", then at least one interrupt is - pending.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x03</entry> - <entry>write/read</entry> - <entrytbl cols="5"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <colspec colnum="5" colname="col5"> - <spanspec namest="col1" nameend="col5" spanname="1to5"> - <spanspec namest="col2" nameend="col5" spanname="2to5"> - <spanspec namest="col4" nameend="col5" spanname="4to5"> - - <tbody> - <row> - <entry spanname="1to5">Line Control Register - (LCR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to5">Divisor Latch Access Bit - (DLAB). When set, access to the data - transmit/receive register (THR/RBR) and the - Interrupt Enable Register (IER) is disabled. Any - access to these ports is now redirected to the - Divisor Latch Registers. Setting this bit, loading - the Divisor Registers, and clearing DLAB should be - done with interrupts disabled.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to5">Set Break. When set to "1", - the transmitter begins to transmit continuous - Spacing until this bit is set to "0". This - overrides any bits of characters that are being - transmitted.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to5">Stick Parity. When parity is - enabled, setting this bit causes parity to always be - "1" or "0", based on the value of Bit 4.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to5">Even Parity Select (EPS). When - parity is enabled and Bit 5 is "0", setting this bit - causes even parity to be transmitted and expected. - Otherwise, odd parity is used.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to5">Parity Enable (PEN). When set - to "1", a parity bit is inserted between the last - bit of the data and the Stop Bit. The UART will - also expect parity to be present in the received - data.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to5">Number of Stop Bits (STB). If - set to "1" and using 5-bit data words, 1.5 Stop Bits - are transmitted and expected in each data word. For - 6, 7 and 8-bit data words, 2 Stop Bits are - transmitted and expected. When this bit is set to - "0", one Stop Bit is used on each data word.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to5">Word Length Select Bit #1 - (WLSB1)</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to5">Word Length Select Bit #0 - (WLSB0)</entry> - </row> - - <row> - <entry colname="col2" spanname="2to5">Together these - bits specify the number of bits in each data - word.</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">Word - Length</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">5 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4" spanname="4to5">6 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">7 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4" spanname="4to5">8 Data - Bits</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x04</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Modem Control Register - (MCR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Loop-Back Enable. When set to "1", the UART - transmitter and receiver are internally connected - together to allow diagnostic operations. In - addition, the UART modem control outputs are - connected to the UART modem control inputs. CTS is - connected to RTS, DTR is connected to DSR, OUT1 is - connected to RI, and OUT 2 is connected to - DCD.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>OUT 2. An auxiliary output that the host - processor may set high or low. In the IBM PC serial - adapter (and most clones), OUT 2 is used to - tri-state (disable) the interrupt signal from the - 8250/16450/16550 UART.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>OUT 1. An auxiliary output that the host - processor may set high or low. This output is not - used on the IBM PC serial adapter.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Request to Send (RTS). When set to "1", the - output of the UART -RTS line is Low - (Active).</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Data Terminal Ready (DTR). When set to "1", - the output of the UART -DTR line is Low - (Active).</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x05</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Line Status Register - (LSR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Error in Receiver FIFO. On the 8250/16450 - UART, this bit is zero. This bit is set to "1" when - any of the bytes in the FIFO have one or more of the - following error conditions: PE, FE, or BI.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Transmitter Empty (TEMT). When set to "1", - there are no words remaining in the transmit FIFO - or the transmit shift register. The transmitter is - completely idle.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Transmitter Holding Register Empty (THRE). - When set to "1", the FIFO (or holding register) now - has room for at least one additional word to - transmit. The transmitter may still be transmitting - when this bit is set to "1".</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Break Interrupt (BI). The receiver has - detected a Break signal.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Framing Error (FE). A Start Bit was detected - but the Stop Bit did not appear at the expected - time. The received word is probably - garbled.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Parity Error (PE). The parity bit was - incorrect for the word received.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Overrun Error (OE). A new word was received - and there was no room in the receive buffer. The - newly-arrived word in the shift register is - discarded. On 8250/16450 UARTs, the word in the - holding register is discarded and the newly- arrived - word is put in the holding register.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Data Ready (DR) One or more words are in the - receive FIFO that the host may read. A word must be - completely received and moved from the shift - register into the FIFO (or holding register for - 8250/16450 designs) before this bit is set.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x06</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Modem Status Register - (MSR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Data Carrier Detect (DCD). Reflects the state - of the DCD line on the UART.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Ring Indicator (RI). Reflects the state of the - RI line on the UART.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Data Set Ready (DSR). Reflects the state of - the DSR line on the UART.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Clear To Send (CTS). Reflects the state of the - CTS line on the UART.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Delta Data Carrier Detect (DDCD). Set to "1" - if the -DCD line has changed state one more more - times since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Trailing Edge Ring Indicator (TERI). Set to - "1" if the -RI line has had a low to high transition - since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Delta Data Set Ready (DDSR). Set to "1" if the - -DSR line has changed state one more more times - since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Delta Clear To Send (DCTS). Set to "1" if the - -CTS line has changed state one more more times - since the last time the MSR was read by the - host.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x07</entry> - <entry>write/read</entry> - <entry>Scratch Register (SCR). This register performs no - function in the UART. Any value can be written by the - host to this location and read by the host later - on.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect4> - - <sect4> - <title>Beyond the 16550A UART</title> - - <para>Although National Semiconductor has not offered any components - compatible with the 16550 that provide additional features, - various other vendors have. Some of these components are - described below. It should be understood that to effectively - utilize these improvements, drivers may have to be provided by the - chip vendor since most of the popular operating systems do not - support features beyond those provided by the 16550.</para> - - <variablelist> - <varlistentry> - <term>ST16650</term> - - <listitem> - <para>By default this part is similar to the NS16550A, but an - extended 32-byte send and receive buffer can be optionally - enabled. Made by Startech.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>TIL16660</term> - - <listitem> - <para>By default this part behaves similar to the NS16550A, - but an extended 64-byte send and receive buffer can be - optionally enabled. Made by Texas Instruments.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Hayes ESP</term> - - <listitem> - <para>This proprietary plug-in card contains a 2048-byte send - and receive buffer, and supports data rates to - 230.4Kbit/sec. Made by Hayes.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In addition to these “dumb” UARTs, many vendors - produce intelligent serial communication boards. This type of - design usually provides a microprocessor that interfaces with - several UARTs, processes and buffers the data, and then alerts the - main PC processor when necessary. Because the UARTs are not - directly accessed by the PC processor in this type of - communication system, it is not necessary for the vendor to use - UARTs that are compatible with the 8250, 16450, or the 16550 UART. - This leaves the designer free to components that may have better - performance characteristics.</para> - </sect4> - </sect3> - - <sect3 id="sio"> - <title>Configuring the <devicename>sio</devicename> driver</title> - - <para>The <devicename>sio</devicename> driver provides support for - NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT - V.24) communications interfaces. Several multiport cards are - supported as well. See the &man.sio.4; - manual page for detailed technical documentation.</para> - - <sect4> - <title>Digi International (DigiBoard) PC/8</title> - - <para><emphasis>Contributed by &a.awebster;. 26 August - 1995.</emphasis></para> - - <para>Here is a config snippet from a machine with a Digi - International PC/8 with 16550. It has 8 modems connected to these - 8 lines, and they work just great. Do not forget to add - <literal>options COM_MULTIPORT</literal> or it will not work very - well!</para> - - <programlisting> -device sio4 at isa? port 0x100 tty flags 0xb05 -device sio5 at isa? port 0x108 tty flags 0xb05 -device sio6 at isa? port 0x110 tty flags 0xb05 -device sio7 at isa? port 0x118 tty flags 0xb05 -device sio8 at isa? port 0x120 tty flags 0xb05 -device sio9 at isa? port 0x128 tty flags 0xb05 -device sio10 at isa? port 0x130 tty flags 0xb05 -device sio11 at isa? port 0x138 tty flags 0xb05 irq 9 vector siointr</programlisting> - - <para>The trick in setting this up is that the MSB of the flags - represent the last SIO port, in this case 11 so flags are - 0xb05.</para> - </sect4> - - <sect4> - <title>Boca 16</title> - - <para><emphasis>Contributed by &a.whiteside;. 26 August - 1995.</emphasis></para> - - <para>The procedures to make a Boca 16 port board with FreeBSD are - pretty straightforward, but you will need a couple things to make - it work:</para> - - <orderedlist> - <listitem> - <para>You either need the kernel sources installed so you can - recompile the necessary options or you will need someone else - to compile it for you. The 2.0.5 default kernel does - <emphasis>not</emphasis> come with multiport support enabled - and you will need to add a device entry for each port - anyways.</para> - </listitem> - - <listitem> - <para>Two, you will need to know the interrupt and IO setting - for your Boca Board so you can set these options properly in - the kernel.</para> - </listitem> - </orderedlist> - - <para>One important note — the actual UART chips for the Boca - 16 are in the connector box, not on the internal board itself. So - if you have it unplugged, probes of those ports will fail. I have - never tested booting with the box unplugged and plugging it back - in, and I suggest you do not either.</para> - - <para>If you do not already have a custom kernel configuration file - set up, refer to <link linkend="kernelconfig">Kernel - Configuration</link> for general procedures. The following are - the specifics for the Boca 16 board and assume you are using the - kernel name MYKERNEL and editing with vi.</para> - - <procedure> - <step> - <para>Add the line - - <programlisting> -options COM_MULTIPORT</programlisting> - - to the config file.</para> - </step> - - <step> - <para>Where the current <literal>device - sio<replaceable>n</replaceable></literal> lines are, you - will need to add 16 more devices. Only the last device - includes the interrupt vector for the board. (See the - &man.sio.4; manual page for detail as - to why.) The following example is for a Boca Board with an - interrupt of 3, and a base IO address 100h. The IO address - for Each port is +8 hexadecimal from the previous port, thus - the 100h, 108h, 110h... addresses.</para> - - <programlisting> -device sio1 at isa? port 0x100 tty flags 0x1005 -device sio2 at isa? port 0x108 tty flags 0x1005 -device sio3 at isa? port 0x110 tty flags 0x1005 -device sio4 at isa? port 0x118 tty flags 0x1005 -… -device sio15 at isa? port 0x170 tty flags 0x1005 -device sio16 at isa? port 0x178 tty flags 0x1005 irq 3 vector siointr</programlisting> - - <para>The flags entry <emphasis>must</emphasis> be changed from - this example unless you are using the exact same sio - assignments. Flags are set according to - 0x<replaceable>M</replaceable><replaceable>YY</replaceable> - where <replaceable>M</replaceable> indicates the minor number - of the master port (the last port on a Boca 16) and - <replaceable>YY</replaceable> indicates if FIFO is enabled or - disabled(enabled), IRQ sharing is used(yes) and if there is an - AST/4 compatible IRQ control register(no). In this example, - <programlisting> flags 0x1005</programlisting> indicates that - the master port is sio16. If I added another board and - assigned sio17 through sio28, the flags for all 16 ports on - <emphasis>that</emphasis> board would be 0x1C05, where 1C - indicates the minor number of the master port. Do not change - the 05 setting.</para> - </step> - - <step> - <para>Save and complete the kernel configuration, recompile, - install and reboot. Presuming you have successfully installed - the recompiled kernel and have it set to the correct address - and IRQ, your boot message should indicate the successful - probe of the Boca ports as follows: (obviously the sio - numbers, IO and IRQ could be different)</para> - - <screen>sio1 at 0x100-0x107 flags 0x1005 on isa -sio1: type 16550A (multiport) -sio2 at 0x108-0x10f flags 0x1005 on isa -sio2: type 16550A (multiport) -sio3 at 0x110-0x117 flags 0x1005 on isa -sio3: type 16550A (multiport) -sio4 at 0x118-0x11f flags 0x1005 on isa -sio4: type 16550A (multiport) -sio5 at 0x120-0x127 flags 0x1005 on isa -sio5: type 16550A (multiport) -sio6 at 0x128-0x12f flags 0x1005 on isa -sio6: type 16550A (multiport) -sio7 at 0x130-0x137 flags 0x1005 on isa -sio7: type 16550A (multiport) -sio8 at 0x138-0x13f flags 0x1005 on isa -sio8: type 16550A (multiport) -sio9 at 0x140-0x147 flags 0x1005 on isa -sio9: type 16550A (multiport) -sio10 at 0x148-0x14f flags 0x1005 on isa -sio10: type 16550A (multiport) -sio11 at 0x150-0x157 flags 0x1005 on isa -sio11: type 16550A (multiport) -sio12 at 0x158-0x15f flags 0x1005 on isa -sio12: type 16550A (multiport) -sio13 at 0x160-0x167 flags 0x1005 on isa -sio13: type 16550A (multiport) -sio14 at 0x168-0x16f flags 0x1005 on isa -sio14: type 16550A (multiport) -sio15 at 0x170-0x177 flags 0x1005 on isa -sio15: type 16550A (multiport) -sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa -sio16: type 16550A (multiport master)</screen> - - <para>If the messages go by too fast to see, - - <screen>&prompt.root; <userinput>dmesg | more</userinput></screen> - will show you the boot messages.</para> - </step> - - <step> - <para>Next, appropriate entries in <filename>/dev</filename> for - the devices must be made using the - <filename>/dev/MAKEDEV</filename> script. After becoming - root:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV tty1</userinput> -&prompt.root; <userinput>./MAKEDEV cua1</userinput> -<emphasis>(everything in between)</emphasis> -&prompt.root; <userinput>./MAKEDEV ttyg</userinput> -&prompt.root; <userinput>./MAKEDEV cuag</userinput></screen> - - <para>If you do not want or need callout devices for some - reason, you can dispense with making the - <filename>cua*</filename> devices.</para> - </step> - - <step> - <para>If you want a quick and sloppy way to make sure the - devices are working, you can simply plug a modem into each - port and (as root) - - <screen>&prompt.root; <userinput>echo at > ttyd*</userinput></screen> - for each device you have made. You - <emphasis>should</emphasis> see the RX lights flash for each - working port.</para> - </step> - </procedure> - </sect4> - </sect3> - - <sect3 id="cy"> - <title>Configuring the <devicename>cy</devicename> driver</title> - - <para><emphasis>Contributed by &a.alex;. 6 June - 1996.</emphasis></para> - - <para>The Cyclades multiport cards are based on the - <devicename>cy</devicename> driver instead of the usual - <devicename>sio</devicename> driver used by other multiport cards. - Configuration is a simple matter of:</para> - - <procedure> - <step> - <para>Add the <devicename>cy</devicename> device to your <link - linkend="kernelconfig-config">kernel configuration</link> - (note that your irq and iomem settings may differ).</para> - - <programlisting> -device cy0 at isa? tty irq 10 iomem 0xd4000 iosiz 0x2000 vector cyintr</programlisting> - </step> - - <step> - <para><link linkend="kernelconfig-building">Rebuild and - install</link> the new kernel.</para> - </step> - - <step> - <para>Make the <link linkend="kernelconfig-nodes">device - nodes</link> by typing (the following example assumes an - 8-port board):</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done</userinput></screen> - </step> - - <step> - <para>If appropriate, add <link linkend="dialup">dialup</link> - entries to <link linkend="dialup-ttys">/etc/ttys</link> by - duplicating serial device (<literal>ttyd</literal>) entries and - using <literal>ttyc</literal> in place of - <literal>ttyd</literal>. For example:</para> - - <programlisting> -ttyc0 "/usr/libexec/getty std.38400" unknown on insecure -ttyc1 "/usr/libexec/getty std.38400" unknown on insecure -ttyc2 "/usr/libexec/getty std.38400" unknown on insecure -… -ttyc7 "/usr/libexec/getty std.38400" unknown on insecure</programlisting> - </step> - - <step> - <para>Reboot with the new kernel.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Configuring the <devicename>si</devicename> driver</title> - - <para><emphasis>Contributed by &a.nsayer;. 25 March - 1998.</emphasis></para> - - <para>The Specialix SI/XIO and SX multiport cards use the - <devicename>si</devicename> driver. A single machine can - have up to 4 host cards. The following host cards - are supported:</para> - - <itemizedlist> - <listitem><para>ISA SI/XIO host card (2 versions)</para></listitem> - <listitem><para>EISA SI/XIO host card</para></listitem> - <listitem><para>PCI SI/XIO host card</para></listitem> - <listitem><para>ISA SX host card</para></listitem> - <listitem><para>PCI SX host card</para></listitem> - </itemizedlist> - - <para>Although the SX and SI/XIO host cards look markedly different, - their functionality are basically the same. The host cards do not - use I/O locations, but instead require a 32K chunk of memory. The - factory configuration for ISA cards places this at - <literal>0xd0000-0xd7fff</literal>. - They also require an IRQ. PCI cards will, of course, autoconfigure - themselves.</para> - - <para>You can attach up to 4 external modules to each host card. The - external modules contain either 4 or 8 serial ports. They come in - the following varieties:</para> - - <itemizedlist> - <listitem><para>SI 4 or 8 port modules. Up to 57600 bps on each port - supported.</para></listitem> - - <listitem><para>XIO 8 port modules. Up to 115200 bps on each port - supported. One type of XIO module has 7 serial and 1 parallel - port.</para></listitem> - - <listitem><para>SXDC 8 port modules. Up to 921600 bps on each port - supported. Like XIO, a module is available with one parallel - port as well.</para></listitem> - </itemizedlist> - - <para>To configure an ISA host card, add the following line to your - <link linkend="kernelconfig-config">kernel configuration - file</link>, changing the numbers as appropriate:</para> - - <programlisting> -device si0 at isa? tty iomem 0xd0000 irq 11</programlisting> - - <para>Valid IRQ numbers are 9, 10, 11, 12 and 15 for SX ISA host cards - and 11, 12 and 15 for SI/XIO ISA host cards.</para> - - <para>To configure an EISA or PCI host card, use this line:</para> - - <programlisting> -device si0</programlisting> - - <para>After adding the configuration entry, <link - linkend="kernelconfig-building"> rebuild and install</link> your - new kernel.</para> - - <para>After rebooting with the new kernel, you need to make the <link - linkend="kernelconfig-nodes"> device nodes</link> in /dev. The - <filename>MAKEDEV</filename> script will take care of this for you. - Count how many total ports you have and type:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV ttyA<replaceable>nn</replaceable> cuaA<replaceable>nn</replaceable></userinput></screen> - - <para>(where <replaceable>nn</replaceable> is the number of - ports)</para> - - <para>If you want login prompts to appear on these ports, you will - need to add lines like this to <link - linkend="dialup"><filename>/etc/ttys</filename></link>:</para> - - <programlisting> -ttyA01 "/usr/libexec/getty std.9600" vt100 on insecure - </programlisting> - - <para>Change the terminal type as appropriate. For modems, - <userinput>dialup</userinput> or <userinput>unknown</userinput> is - fine.</para> - </sect3> - </sect2> - - <sect2> - <title>* Parallel ports</title> - - <para></para> - </sect2> - - <sect2> - <title>* Modems</title> - - <para></para> - </sect2> - - <sect2> - <title>* Network cards</title> - - <para></para> - </sect2> - - <sect2> - <title>* Keyboards</title> - - <para></para> - </sect2> - - <sect2> - <title>* Mice</title> - - <para></para> - </sect2> - - <sect2> - <title>* Other</title> - - <para></para> - </sect2> - </sect1> - - <sect1 id="hw-storage"> - <title>Storage Devices</title> - - <sect2 id="esdi"> - <title>Using ESDI hard disks</title> - - <para><emphasis>Copyright © 1995, &a.wilko;. 24 - September 1995.</emphasis></para> - - <para>ESDI is an acronym that means Enhanced Small Device Interface. It - is loosely based on the good old ST506/412 interface originally - devised by Seagate Technology, the makers of the first affordable - 5.25" winchester disk.</para> - - <para>The acronym says Enhanced, and rightly so. In the first place the - speed of the interface is higher, 10 or 15 Mbits/second instead of the - 5 Mbits/second of ST412 interfaced drives. Secondly some higher level - commands are added, making the ESDI interface somewhat 'smarter' to - the operating system driver writers. It is by no means as smart as - SCSI by the way. ESDI is standardized by ANSI.</para> - - <para>Capacities of the drives are boosted by putting more sectors on - each track. Typical is 35 sectors per track, high capacity drives I - have seen were up to 54 sectors/track.</para> - - <para>Although ESDI has been largely obsoleted by IDE and SCSI - interfaces, the availability of free or cheap surplus drives makes - them ideal for low (or now) budget systems.</para> - - <sect3> - <title>Concepts of ESDI</title> - - <sect4> - <title>Physical connections</title> - - <para>The ESDI interface uses two cables connected to each drive. - One cable is a 34 pin flat cable edge connector that carries the - command and status signals from the controller to the drive and - vice-versa. The command cable is daisy chained between all the - drives. So, it forms a bus onto which all drives are - connected.</para> - - <para>The second cable is a 20 pin flat cable edge connector that - carries the data to and from the drive. This cable is radially - connected, so each drive has its own direct connection to the - controller.</para> - - <para>To the best of my knowledge PC ESDI controllers are limited to - using a maximum of 2 drives per controller. This is compatibility - feature(?) left over from the WD1003 standard that reserves only a - single bit for device addressing.</para> - </sect4> - - <sect4> - <title>Device addressing</title> - - <para>On each command cable a maximum of 7 devices and 1 controller - can be present. To enable the controller to uniquely identify - which drive it addresses, each ESDI device is equipped with - jumpers or switches to select the devices address.</para> - - <para>On PC type controllers the first drive is set to address 0, - the second disk to address 1. <emphasis>Always make - sure</emphasis> you set each disk to an unique address! So, on a - PC with its two drives/controller maximum the first drive is drive - 0, the second is drive 1.</para> - </sect4> - - <sect4> - <title>Termination</title> - - <para>The daisy chained command cable (the 34 pin cable remember?) - needs to be terminated at the last drive on the chain. For this - purpose ESDI drives come with a termination resistor network that - can be removed or disabled by a jumper when it is not used.</para> - - <para>So, one and <emphasis>only</emphasis> one drive, the one at - the farthest end of the command cable has its terminator - installed/enabled. The controller automatically terminates the - other end of the cable. Please note that this implies that the - controller must be at one end of the cable and - <emphasis>not</emphasis> in the middle.</para> - </sect4> - </sect3> - - <sect3> - <title>Using ESDI disks with FreeBSD</title> - - <para>Why is ESDI such a pain to get working in the first - place?</para> - - <para>People who tried ESDI disks with FreeBSD are known to have - developed a profound sense of frustration. A combination of factors - works against you to produce effects that are hard to understand - when you have never seen them before.</para> - - <para>This has also led to the popular legend ESDI and FreeBSD is a - plain NO-GO. The following sections try to list all the pitfalls - and solutions.</para> - - <sect4> - <title>ESDI speed variants</title> - - <para>As briefly mentioned before, ESDI comes in two speed flavors. - The older drives and controllers use a 10 Mbits/second data - transfer rate. Newer stuff uses 15 Mbits/second.</para> - - <para>It is not hard to imagine that 15 Mbits/second drive cause - problems on controllers laid out for 10 Mbits/second. As always, - consult your controller <emphasis>and</emphasis> drive - documentation to see if things match.</para> - </sect4> - - <sect4> - <title>Stay on track</title> - - <para>Mainstream ESDI drives use 34 to 36 sectors per track. Most - (older) controllers cannot handle more than this number of - sectors. Newer, higher capacity, drives use higher numbers of - sectors per track. For instance, I own a 670 Mb drive that has 54 - sectors per track.</para> - - <para>In my case, the controller could not handle this number of - sectors. It proved to work well except that it only used 35 - sectors on each track. This meant losing a lot of disk - space.</para> - - <para>Once again, check the documentation of your hardware for more - info. Going out-of-spec like in the example might or might not - work. Give it a try or get another more capable - controller.</para> - </sect4> - - <sect4> - <title>Hard or soft sectoring</title> - - <para>Most ESDI drives allow hard or soft sectoring to be selected - using a jumper. Hard sectoring means that the drive will produce - a sector pulse on the start of each new sector. The controller - uses this pulse to tell when it should start to write or - read.</para> - - <para>Hard sectoring allows a selection of sector size (normally - 256, 512 or 1024 bytes per formatted sector). FreeBSD uses 512 - byte sectors. The number of sectors per track also varies while - still using the same number of bytes per formatted sector. The - number of <emphasis>unformatted</emphasis> bytes per sector - varies, dependent on your controller it needs more or less - overhead bytes to work correctly. Pushing more sectors on a - track of course gives you more usable space, but might give - problems if your controller needs more bytes than the drive - offers.</para> - - <para>In case of soft sectoring, the controller itself determines - where to start/stop reading or writing. For ESDI hard sectoring - is the default (at least on everything I came across). I never - felt the urge to try soft sectoring.</para> - - <para>In general, experiment with sector settings before you install - FreeBSD because you need to re-run the low-level format after each - change.</para> - </sect4> - - <sect4> - <title>Low level formatting</title> - - <para>ESDI drives need to be low level formatted before they are - usable. A reformat is needed whenever you figgle with the number - of sectors/track jumpers or the physical orientation of the drive - (horizontal, vertical). So, first think, then format. The format - time must not be underestimated, for big disks it can take - hours.</para> - - <para>After a low level format, a surface scan is done to find and - flag bad sectors. Most disks have a manufacturer bad block list - listed on a piece of paper or adhesive sticker. In addition, on - most disks the list is also written onto the disk. Please use the - manufacturer's list. It is much easier to remap a defect now than - after FreeBSD is installed.</para> - - <para>Stay away from low-level formatters that mark all sectors of a - track as bad as soon as they find one bad sector. Not only does - this waste space, it also and more importantly causes you grief - with bad144 (see the section on bad144).</para> - </sect4> - - <sect4> - <title>Translations</title> - - <para>Translations, although not exclusively a ESDI-only problem, - might give you real trouble. Translations come in multiple - flavors. Most of them have in common that they attempt to work - around the limitations posed upon disk geometries by the original - IBM PC/AT design (thanks IBM!).</para> - - <para>First of all there is the (in)famous 1024 cylinder limit. For - a system to be able to boot, the stuff (whatever operating system) - must be in the first 1024 cylinders of a disk. Only 10 bits are - available to encode the cylinder number. For the number of - sectors the limit is 64 (0-63). When you combine the 1024 - cylinder limit with the 16 head limit (also a design feature) you - max out at fairly limited disk sizes.</para> - - <para>To work around this problem, the manufacturers of ESDI PC - controllers added a BIOS prom extension on their boards. This - BIOS extension handles disk I/O for booting (and for some - operating systems <emphasis>all</emphasis> disk I/O) by using - translation. For instance, a big drive might be presented to the - system as having 32 heads and 64 sectors/track. The result is - that the number of cylinders is reduced to something below 1024 - and is therefore usable by the system without problems. It is - noteworthy to know that FreeBSD does not use the BIOS after its - kernel has started. More on this later.</para> - - <para>A second reason for translations is the fact that most older - system BIOSes could only handle drives with 17 sectors per track - (the old ST412 standard). Newer system BIOSes usually have a - user-defined drive type (in most cases this is drive type - 47).</para> - - <warning> - <para>Whatever you do to translations after reading this document, - keep in mind that if you have multiple operating systems on the - same disk, all must use the same translation</para> - </warning> - - <para>While on the subject of translations, I have seen one - controller type (but there are probably more like this) offer the - option to logically split a drive in multiple partitions as a BIOS - option. I had select 1 drive == 1 partition because this - controller wrote this info onto the disk. On power-up it read the - info and presented itself to the system based on the info from the - disk.</para> - </sect4> - - <sect4> - <title>Spare sectoring</title> - - <para>Most ESDI controllers offer the possibility to remap bad - sectors. During/after the low-level format of the disk bad - sectors are marked as such, and a replacement sector is put in - place (logically of course) of the bad one.</para> - - <para>In most cases the remapping is done by using N-1 sectors on - each track for actual data storage, and sector N itself is the - spare sector. N is the total number of sectors physically - available on the track. The idea behind this is that the - operating system sees a 'perfect' disk without bad sectors. In - the case of FreeBSD this concept is not usable.</para> - - <para>The problem is that the translation from - <emphasis>bad</emphasis> to <emphasis>good</emphasis> is performed - by the BIOS of the ESDI controller. FreeBSD, being a true 32 bit - operating system, does not use the BIOS after it has been booted. - Instead, it has device drivers that talk directly to the - hardware.</para> - - <para><emphasis>So: don't use spare sectoring, bad block remapping - or whatever it may be called by the controller manufacturer when - you want to use the disk for FreeBSD.</emphasis></para> - </sect4> - - <sect4> - <title>Bad block handling</title> - - <para>The preceding section leaves us with a problem. The - controller's bad block handling is not usable and still FreeBSD's - filesystems assume perfect media without any flaws. To solve this - problem, FreeBSD use the <command>bad144</command> tool. Bad144 - (named after a Digital Equipment standard for bad block handling) - scans a FreeBSD slice for bad blocks. Having found these bad - blocks, it writes a table with the offending block numbers to the - end of the FreeBSD slice.</para> - - <para>When the disk is in operation, the disk accesses are checked - against the table read from the disk. Whenever a block number is - requested that is in the <command>bad144</command> list, a - replacement block (also from the end of the FreeBSD slice) is - used. In this way, the <command>bad144</command> replacement - scheme presents 'perfect' media to the FreeBSD filesystems.</para> - - <para>There are a number of potential pitfalls associated with the - use of <command>bad144</command>. First of all, the slice cannot - have more than 126 bad sectors. If your drive has a high number - of bad sectors, you might need to divide it into multiple FreeBSD - slices each containing less than 126 bad sectors. Stay away from - low-level format programs that mark <emphasis>every</emphasis> - sector of a track as bad when they find a flaw on the track. As - you can imagine, the 126 limit is quickly reached when the - low-level format is done this way.</para> - - <para>Second, if the slice contains the root filesystem, the slice - should be within the 1024 cylinder BIOS limit. During the boot - process the bad144 list is read using the BIOS and this only - succeeds when the list is within the 1024 cylinder limit.</para> - - <note> - <para>The restriction is not that only the root - <emphasis>filesystem</emphasis> must be within the 1024 cylinder - limit, but rather the entire <emphasis>slice</emphasis> that - contains the root filesystem.</para> - </note> - </sect4> - - <sect4> - <title>Kernel configuration</title> - - <para>ESDI disks are handled by the same <literal>wd</literal>driver - as IDE and ST412 MFM disks. The <literal>wd</literal> driver - should work for all WD1003 compatible interfaces.</para> - - <para>Most hardware is jumperable for one of two different I/O - address ranges and IRQ lines. This allows you to have two wd - type controllers in one system.</para> - - <para>When your hardware allows non-standard strappings, you can use - these with FreeBSD as long as you enter the correct info into the - kernel config file. An example from the kernel config file (they - live in <filename>/sys/i386/conf</filename> BTW).</para> - - <programlisting> -# First WD compatible controller -controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr -disk wd0 at wdc0 drive 0 -disk wd1 at wdc0 drive 1 -# Second WD compatible controller -controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr -disk wd2 at wdc1 drive 0 -disk wd3 at wdc1 drive 1</programlisting> - </sect4> - </sect3> - - <sect3> - <title>Particulars on ESDI hardware</title> - - <sect4> - <title>Adaptec 2320 controllers</title> - - <para>I successfully installed FreeBSD onto a ESDI disk controlled - by a ACB-2320. No other operating system was present on the - disk.</para> - - <para>To do so I low level formatted the disk using - <command>NEFMT.EXE</command> (<command>ftp</command>able from - <hostid role="fqdn">www.adaptec.com</hostid>) and answered NO to - the question whether the disk should be formatted with a spare - sector on each track. The BIOS on the ACD-2320 was disabled. I - used the <literal>free configurable</literal> option in the system - BIOS to allow the BIOS to boot it.</para> - - <para>Before using <command>NEFMT.EXE</command> I tried to format - the disk using the ACB-2320 BIOS builtin formatter. This proved - to be a show stopper, because it did not give me an option to - disable spare sectoring. With spare sectoring enabled the FreeBSD - installation process broke down on the <command>bad144</command> - run.</para> - - <para>Please check carefully which - ACB-232<replaceable>xy</replaceable> variant you have. The - <replaceable>x</replaceable> is either <literal>0</literal> or - <literal>2</literal>, indicating a controller without or with a - floppy controller on board.</para> - - <para>The <literal>y</literal> is more interesting. It can either - be a blank, a <literal>A-8</literal> or a <literal>D</literal>. A - blank indicates a plain 10 Mbits/second controller. An - <literal>A-8</literal> indicates a 15 Mbits/second controller - capable of handling 52 sectors/track. A <literal>D</literal> - means a 15 Mbits/second controller that can also handle drives - with > 36 sectors/track (also 52 ?).</para> - - <para>All variations should be capable of using 1:1 interleaving. - Use 1:1, FreeBSD is fast enough to handle it.</para> - </sect4> - - <sect4> - <title>Western Digital WD1007 controllers</title> - - <para>I successfully installed FreeBSD onto a ESDI disk controlled - by a WD1007 controller. To be precise, it was a WD1007-WA2. - Other variations of the WD1007 do exist.</para> - - <para>To get it to work, I had to disable the sector translation and - the WD1007's onboard BIOS. This implied I could not use the - low-level formatter built into this BIOS. Instead, I grabbed - <command>WDFMT.EXE</command> from <hostid - role="fqdn">www.wdc.com</hostid> Running this formatted my drive - just fine.</para> - </sect4> - - <sect4> - <title>Ultrastor U14F controllers</title> - - <para>According to multiple reports from the net, Ultrastor ESDI - boards work OK with FreeBSD. I lack any further info on - particular settings.</para> - </sect4> - </sect3> - - <sect3 id="esdi-further-reading"> - <title>Further reading</title> - - <para>If you intend to do some serious ESDI hacking, you might want to - have the official standard at hand:</para> - - <para>The latest ANSI X3T10 committee document is: Enhanced Small - Device Interface (ESDI) [X3.170-1990/X3.170a-1991] [X3T10/792D - Rev 11]</para> - - <para>On Usenet the newsgroup <ulink - URL="news:comp.periphs">comp.periphs</ulink> is a noteworthy place - to look for more info.</para> - - <para>The World Wide Web (WWW) also proves to be a very handy info - source: For info on Adaptec ESDI controllers see <ulink - URL="http://www.adaptec.com/">http://www.adaptec.com/</ulink>. For - info on Western Digital controllers see <ulink - URL="http://www.wdc.com/">http://www.wdc.com/</ulink>.</para> - </sect3> - - <sect3> - <title>Thanks to...</title> - - <para>Andrew Gordon for sending me an Adaptec 2320 controller and ESDI - disk for testing.</para> - </sect3> - </sect2> - - <sect2 id="scsi"> - <title>What is SCSI?</title> - - <para><emphasis>Copyright © 1995, &a.wilko;. July 6, - 1996.</emphasis></para> - - <para>SCSI is an acronym for Small Computer Systems Interface. It is an - ANSI standard that has become one of the leading I/O buses in the - computer industry. The foundation of the SCSI standard was laid by - Shugart Associates (the same guys that gave the world the first mini - floppy disks) when they introduced the SASI bus (Shugart Associates - Standard Interface).</para> - - <para>After some time an industry effort was started to come to a more - strict standard allowing devices from different vendors to work - together. This effort was recognized in the ANSI SCSI-1 standard. - The SCSI-1 standard (approx 1985) is rapidly becoming obsolete. The - current standard is SCSI-2 (see <link - linkend="scsi-further-reading">Further reading</link>), with SCSI-3 - on the drawing boards.</para> - - <para>In addition to a physical interconnection standard, SCSI defines a - logical (command set) standard to which disk devices must adhere. - This standard is called the Common Command Set (CCS) and was developed - more or less in parallel with ANSI SCSI-1. SCSI-2 includes the - (revised) CCS as part of the standard itself. The commands are - dependent on the type of device at hand. It does not make much sense - of course to define a Write command for a scanner.</para> - - <para>The SCSI bus is a parallel bus, which comes in a number of - variants. The oldest and most used is an 8 bit wide bus, with - single-ended signals, carried on 50 wires. (If you do not know what - single-ended means, do not worry, that is what this document is all - about.) Modern designs also use 16 bit wide buses, with differential - signals. This allows transfer speeds of 20Mbytes/second, on cables - lengths of up to 25 meters. SCSI-2 allows a maximum bus width of 32 - bits, using an additional cable. Quickly emerging are Ultra SCSI (also - called Fast-20) and Ultra2 (also called Fast-40). Fast-20 is 20 - million transfers per second (20 Mbytes/sec on a 8 bit bus), Fast-40 - is 40 million transfers per second (40 Mbytes/sec on a 8 bit bus). - Most hard drives sold today are single-ended Ultra SCSI (8 or 16 - bits).</para> - - <para>Of course the SCSI bus not only has data lines, but also a number - of control signals. A very elaborate protocol is part of the standard - to allow multiple devices to share the bus in an efficient manner. In - SCSI-2, the data is always checked using a separate parity line. In - pre-SCSI-2 designs parity was optional.</para> - - <para>In SCSI-3 even faster bus types are introduced, along with a - serial SCSI busses that reduces the cabling overhead and allows a - higher maximum bus length. You might see names like SSA and - Fiberchannel in this context. None of the serial buses are currently - in widespread use (especially not in the typical FreeBSD environment). - For this reason the serial bus types are not discussed any - further.</para> - - <para>As you could have guessed from the description above, SCSI devices - are intelligent. They have to be to adhere to the SCSI standard - (which is over 2 inches thick BTW). So, for a hard disk drive for - instance you do not specify a head/cylinder/sector to address a - particular block, but simply the number of the block you want. - Elaborate caching schemes, automatic bad block replacement etc are all - made possible by this 'intelligent device' approach.</para> - - <para>On a SCSI bus, each possible pair of devices can communicate. - Whether their function allows this is another matter, but the standard - does not restrict it. To avoid signal contention, the 2 devices have - to arbitrate for the bus before using it.</para> - - <para>The philosophy of SCSI is to have a standard that allows - older-standard devices to work with newer-standard ones. So, an old - SCSI-1 device should normally work on a SCSI-2 bus. I say Normally, - because it is not absolutely sure that the implementation of an old - device follows the (old) standard closely enough to be acceptable on a - new bus. Modern devices are usually more well-behaved, because the - standardization has become more strict and is better adhered to by the - device manufacturers.</para> - - <para>Generally speaking, the chances of getting a working set of - devices on a single bus is better when all the devices are SCSI-2 or - newer. This implies that you do not have to dump all your old stuff - when you get that shiny 2GB disk: I own a system on which a pre-SCSI-1 - disk, a SCSI-2 QIC tape unit, a SCSI-1 helical scan tape unit and 2 - SCSI-1 disks work together quite happily. From a performance - standpoint you might want to separate your older and newer (=faster) - devices however.</para> - - <sect3> - <title>Components of SCSI</title> - - <para>As said before, SCSI devices are smart. The idea is to put the - knowledge about intimate hardware details onto the SCSI device - itself. In this way, the host system does not have to worry about - things like how many heads are hard disks has, or how many tracks - there are on a specific tape device. If you are curious, the - standard specifies commands with which you can query your devices on - their hardware particulars. FreeBSD uses this capability during - boot to check out what devices are connected and whether they need - any special treatment.</para> - - <para>The advantage of intelligent devices is obvious: the device - drivers on the host can be made in a much more generic fashion, - there is no longer a need to change (and qualify!) drivers for every - odd new device that is introduced.</para> - - <para>For cabling and connectors there is a golden rule: get good - stuff. With bus speeds going up all the time you will save yourself - a lot of grief by using good material.</para> - - <para>So, gold plated connectors, shielded cabling, sturdy connector - hoods with strain reliefs etc are the way to go. Second golden rule: - do no use cables longer than necessary. I once spent 3 days hunting - down a problem with a flaky machine only to discover that shortening - the SCSI bus by 1 meter solved the problem. And the original bus - length was well within the SCSI specification.</para> - </sect3> - - <sect3> - <title>SCSI bus types</title> - - <para>From an electrical point of view, there are two incompatible bus - types: single-ended and differential. This means that there are two - different main groups of SCSI devices and controllers, which cannot - be mixed on the same bus. It is possible however to use special - converter hardware to transform a single-ended bus into a - differential one (and vice versa). The differences between the bus - types are explained in the next sections.</para> - - <para>In lots of SCSI related documentation there is a sort of jargon - in use to abbreviate the different bus types. A small list:</para> - - <itemizedlist> - <listitem> - <para>FWD: Fast Wide Differential</para> - </listitem> - - <listitem> - <para>FND: Fast Narrow Differential</para> - </listitem> - - <listitem> - <para>SE: Single Ended</para> - </listitem> - - <listitem> - <para>FN: Fast Narrow</para> - </listitem> - - <listitem> - <para>etc.</para> - </listitem> - </itemizedlist> - - - <para>With a minor amount of imagination one can usually imagine what - is meant.</para> - - <para>Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As - far as I know, the 32 bit variant is not (yet) in use, so wide - normally means 16 bit.</para> - - <para>Fast means that the timing on the bus is somewhat different, so - that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead of 5 - Mbytes/sec for 'slow' SCSI. As discussed before, bus speeds of 20 - and 40 million transfers/second are also emerging (Fast-20 == Ultra - SCSI and Fast-40 == Ultra2 SCSI).</para> - - <note> - <para>The data lines > 8 are only used for data transfers and - device addressing. The transfers of commands and status messages - etc are only performed on the lowest 8 data lines. The standard - allows narrow devices to operate on a wide bus. The usable bus - width is negotiated between the devices. You have to watch your - device addressing closely when mixing wide and narrow.</para> - </note> - - <sect4> - <title>Single ended buses</title> - - <para>A single-ended SCSI bus uses signals that are either 5 Volts - or 0 Volts (indeed, TTL levels) and are relative to a COMMON - ground reference. A singled ended 8 bit SCSI bus has - approximately 25 ground lines, who are all tied to a single `rail' - on all devices. A standard single ended bus has a maximum length - of 6 meters. If the same bus is used with fast-SCSI devices, the - maximum length allowed drops to 3 meters. Fast-SCSI means that - instead of 5Mbytes/sec the bus allows 10Mbytes/sec - transfers.</para> - - <para>Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 million - transfers/second respectively. So, F20 is 20 Mbytes/second on a 8 - bit bus, 40 Mbytes/second on a 16 bit bus etc. For F20 the max - bus length is 1.5 meters, for F40 it becomes 0.75 meters. Be - aware that F20 is pushing the limits quite a bit, so you will - quickly find out if your SCSI bus is electrically sound.</para> - - <note> - <para>If some devices on your bus use 'fast' to communicate your - bus must adhere to the length restrictions for fast - buses!</para> - </note> - - <para>It is obvious that with the newer fast-SCSI devices the bus - length can become a real bottleneck. This is why the differential - SCSI bus was introduced in the SCSI-2 standard.</para> - - <para>For connector pinning and connector types please refer to the - SCSI-2 standard (see <link linkend="scsi-further-reading">Further - reading</link>) itself, connectors etc are listed there in - painstaking detail.</para> - - <para>Beware of devices using non-standard cabling. For instance - Apple uses a 25pin D-type connecter (like the one on serial ports - and parallel printers). Considering that the official SCSI bus - needs 50 pins you can imagine the use of this connector needs some - 'creative cabling'. The reduction of the number of ground wires - they used is a bad idea, you better stick to 50 pins cabling in - accordance with the SCSI standard. For Fast-20 and 40 do not even - think about buses like this.</para> - </sect4> - - <sect4> - <title>Differential buses</title> - - <para>A differential SCSI bus has a maximum length of 25 meters. - Quite a difference from the 3 meters for a single-ended fast-SCSI - bus. The idea behind differential signals is that each bus signal - has its own return wire. So, each signal is carried on a - (preferably twisted) pair of wires. The voltage difference - between these two wires determines whether the signal is asserted - or de-asserted. To a certain extent the voltage difference - between ground and the signal wire pair is not relevant (do not - try 10 kVolts though).</para> - - <para>It is beyond the scope of this document to explain why this - differential idea is so much better. Just accept that - electrically seen the use of differential signals gives a much - better noise margin. You will normally find differential buses in - use for inter-cabinet connections. Because of the lower cost - single ended is mostly used for shorter buses like inside - cabinets.</para> - - <para>There is nothing that stops you from using differential stuff - with FreeBSD, as long as you use a controller that has device - driver support in FreeBSD. As an example, Adaptec marketed the - AHA1740 as a single ended board, whereas the AHA1744 was - differential. The software interface to the host is identical for - both.</para> - </sect4> - - <sect4> - <title>Terminators</title> - - <para>Terminators in SCSI terminology are resistor networks that are - used to get a correct impedance matching. Impedance matching is - important to get clean signals on the bus, without reflections or - ringing. If you once made a long distance telephone call on a bad - line you probably know what reflections are. With 20Mbytes/sec - traveling over your SCSI bus, you do not want signals echoing - back.</para> - - <para>Terminators come in various incarnations, with more or less - sophisticated designs. Of course, there are internal and external - variants. Many SCSI devices come with a number of sockets in - which a number of resistor networks can (must be!) installed. If - you remove terminators from a device, carefully store them. You - will need them when you ever decide to reconfigure your SCSI bus. - There is enough variation in even these simple tiny things to make - finding the exact replacement a frustrating business. There are - also SCSI devices that have a single jumper to enable or disable a - built-in terminator. There are special terminators you can stick - onto a flat cable bus. Others look like external connectors, or a - connector hood without a cable. So, lots of choice as you can - see.</para> - - <para>There is much debate going on if and when you should switch - from simple resistor (passive) terminators to active terminators. - Active terminators contain slightly more elaborate circuit to give - cleaner bus signals. The general consensus seems to be that the - usefulness of active termination increases when you have long - buses and/or fast devices. If you ever have problems with your - SCSI buses you might consider trying an active terminator. Try to - borrow one first, they reputedly are quite expensive.</para> - - <para>Please keep in mind that terminators for differential and - single-ended buses are not identical. You should <emphasis>not - mix</emphasis> the two variants.</para> - - <para>OK, and now where should you install your terminators? This is - by far the most misunderstood part of SCSI. And it is by far the - simplest. The rule is: <emphasis>every single line on the SCSI - bus has 2 (two) terminators, one at each end of the - bus.</emphasis> So, two and not one or three or whatever. Do - yourself a favor and stick to this rule. It will save you endless - grief, because wrong termination has the potential to introduce - highly mysterious bugs. (Note the “potential” here; - the nastiest part is that it may or may not work.)</para> - - <para>A common pitfall is to have an internal (flat) cable in a - machine and also an external cable attached to the controller. It - seems almost everybody forgets to remove the terminators from the - controller. The terminator must now be on the last external - device, and not on the controller! In general, every - reconfiguration of a SCSI bus must pay attention to this.</para> - - <note> - <para>Termination is to be done on a per-line basis. This means - if you have both narrow and wide buses connected to the same - host adapter, you need to enable termination on the higher 8 - bits of the bus on the adapter (as well as the last devices on - each bus, of course).</para> - </note> - - <para>What I did myself is remove all terminators from my SCSI - devices and controllers. I own a couple of external terminators, - for both the Centronics-type external cabling and for the internal - flat cable connectors. This makes reconfiguration much - easier.</para> - - <para>On modern devices, sometimes integrated terminators are used. - These things are special purpose integrated circuits that can be - dis/en-abled with a control pin. It is not necessary to - physically remove them from a device. You may find them on newer - host adapters, sometimes they are software configurable, using - some sort of setup tool. Some will even auto-detect the cables - attached to the connectors and automatically set up the - termination as necessary. At any rate, consult your - documentation!</para> - </sect4> - - <sect4> - <title>Terminator power</title> - - <para>The terminators discussed in the previous chapter need power - to operate properly. On the SCSI bus, a line is dedicated to this - purpose. So, simple huh?</para> - - <para>Not so. Each device can provide its own terminator power to - the terminator sockets it has on-device. But if you have external - terminators, or when the device supplying the terminator power to - the SCSI bus line is switched off you are in trouble.</para> - - <para>The idea is that initiators (these are devices that initiate - actions on the bus, a discussion follows) must supply terminator - power. All SCSI devices are allowed (but not required) to supply - terminator power.</para> - - <para>To allow for un-powered devices on a bus, the terminator power - must be supplied to the bus via a diode. This prevents the - backflow of current to un-powered devices.</para> - - <para>To prevent all kinds of nastiness, the terminator power is - usually fused. As you can imagine, fuses might blow. This can, - but does not have to, lead to a non functional bus. If multiple - devices supply terminator power, a single blown fuse will not put - you out of business. A single supplier with a blown fuse - certainly will. Clever external terminators sometimes have a LED - indication that shows whether terminator power is present.</para> - - <para>In newer designs auto-restoring fuses that 'reset' themselves - after some time are sometimes used.</para> - </sect4> - - <sect4> - <title>Device addressing</title> - - <para>Because the SCSI bus is, ehh, a bus there must be a way to - distinguish or address the different devices connected to - it.</para> - - <para>This is done by means of the SCSI or target ID. Each device - has a unique target ID. You can select the ID to which a device - must respond using a set of jumpers, or a dip switch, or something - similar. Some SCSI host adapters let you change the target ID - from the boot menu. (Yet some others will not let you change the - ID from 7.) Consult the documentation of your device for more - information.</para> - - <para>Beware of multiple devices configured to use the same ID. - Chaos normally reigns in this case. A pitfall is that one of the - devices sharing the same ID sometimes even manages to answer to - I/O requests!</para> - - <para>For an 8 bit bus, a maximum of 8 targets is possible. The - maximum is 8 because the selection is done bitwise using the 8 - data lines on the bus. For wide buses this increases to the - number of data lines (usually 16).</para> - - <note> - <para>A narrow SCSI device can not communicate with a SCSI device - with a target ID larger than 7. This means it is generally not - a good idea to move your SCSI host adapter's target ID to - something higher than 7 (or your CD-ROM will stop - working).</para> - </note> - - <para>The higher the SCSI target ID, the higher the priority the - devices has. When it comes to arbitration between devices that - want to use the bus at the same time, the device that has the - highest SCSI ID will win. This also means that the SCSI host - adapter usually uses target ID 7. Note however that the lower 8 - IDs have higher priorities than the higher 8 IDs on a wide-SCSI - bus. Thus, the order of target IDs is: [7 6 .. 1 0 15 14 .. 9 8] - on a wide-SCSI system. (If you you are wondering why the lower 8 - have higher priority, read the previous paragraph for a - hint.)</para> - - <para>For a further subdivision, the standard allows for Logical - Units or LUNs for short. A single target ID may have multiple - LUNs. For example, a tape device including a tape changer may - have LUN 0 for the tape device itself, and LUN 1 for the tape - changer. In this way, the host system can address each of the - functional units of the tape changer as desired.</para> - </sect4> - - <sect4> - <title>Bus layout</title> - - <para>SCSI buses are linear. So, not shaped like Y-junctions, star - topologies, rings, cobwebs or whatever else people might want to - invent. One of the most common mistakes is for people with - wide-SCSI host adapters to connect devices on all three connecters - (external connector, internal wide connector, internal narrow - connector). Don't do that. It may appear to work if you are - really lucky, but I can almost guarantee that your system will - stop functioning at the most unfortunate moment (this is also - known as “Murphy's law”).</para> - - <para>You might notice that the terminator issue discussed earlier - becomes rather hairy if your bus is not linear. Also, if you have - more connectors than devices on your internal SCSI cable, make - sure you attach devices on connectors on both ends instead of - using the connectors in the middle and let one or both ends - dangle. This will screw up the termination of the bus.</para> - - <para>The electrical characteristics, its noise margins and - ultimately the reliability of it all are tightly related to linear - bus rule.</para> - - <para><emphasis>Stick to the linear bus rule!</emphasis></para> - </sect4> - </sect3> - - <sect3> - <title>Using SCSI with FreeBSD</title> - - <sect4> - <title>About translations, BIOSes and magic...</title> - - <para>As stated before, you should first make sure that you have a - electrically sound bus.</para> - - <para>When you want to use a SCSI disk on your PC as boot disk, you - must aware of some quirks related to PC BIOSes. The PC BIOS in - its first incarnation used a low level physical interface to the - hard disk. So, you had to tell the BIOS (using a setup tool or a - BIOS built-in setup) how your disk physically looked like. This - involved stating number of heads, number of cylinders, number of - sectors per track, obscure things like precompensation and reduced - write current cylinder etc.</para> - - <para>One might be inclined to think that since SCSI disks are smart - you can forget about this. Alas, the arcane setup issue is still - present today. The system BIOS needs to know how to access your - SCSI disk with the head/cyl/sector method in order to load the - FreeBSD kernel during boot.</para> - - <para>The SCSI host adapter or SCSI controller you have put in your - AT/EISA/PCI/whatever bus to connect your disk therefore has its - own on-board BIOS. During system startup, the SCSI BIOS takes - over the hard disk interface routines from the system BIOS. To - fool the system BIOS, the system setup is normally set to No hard - disk present. Obvious, isn't it?</para> - - <para>The SCSI BIOS itself presents to the system a so called - <emphasis>translated</emphasis> drive. This means that a fake - drive table is constructed that allows the PC to boot the drive. - This translation is often (but not always) done using a pseudo - drive with 64 heads and 32 sectors per track. By varying the - number of cylinders, the SCSI BIOS adapts to the actual drive - size. It is useful to note that 32 * 64 / 2 = the size of your - drive in megabytes. The division by 2 is to get from disk blocks - that are normally 512 bytes in size to Kbytes.</para> - - <para>Right. All is well now?! No, it is not. The system BIOS has - another quirk you might run into. The number of cylinders of a - bootable hard disk cannot be greater than 1024. Using the - translation above, this is a show-stopper for disks greater than 1 - GB. With disk capacities going up all the time this is causing - problems.</para> - - <para>Fortunately, the solution is simple: just use another - translation, e.g. with 128 heads instead of 32. In most cases new - SCSI BIOS versions are available to upgrade older SCSI host - adapters. Some newer adapters have an option, in the form of a - jumper or software setup selection, to switch the translation the - SCSI BIOS uses.</para> - - <para>It is very important that <emphasis>all</emphasis> operating - systems on the disk use the <emphasis>same translation</emphasis> - to get the right idea about where to find the relevant partitions. - So, when installing FreeBSD you must answer any questions about - heads/cylinders etc using the translated values your host adapter - uses.</para> - - <para>Failing to observe the translation issue might lead to - un-bootable systems or operating systems overwriting each others - partitions. Using fdisk you should be able to see all - partitions.</para> - - <para>You might have heard some talk of “lying” devices? - Older FreeBSD kernels used to report the geometry of SCSI disks - when booting. An example from one of my systems:</para> - - <screen>aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> -sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512</screen> - - <para>Newer kernels usually do not report this information. - e.g.</para> - - <screen>(bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2 -sd0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors)</screen> - - <para>Why has this changed?</para> - - <para>This info is retrieved from the SCSI disk itself. Newer disks - often use a technique called zone bit recording. The idea is that - on the outer cylinders of the drive there is more space so more - sectors per track can be put on them. This results in disks that - have more tracks on outer cylinders than on the inner cylinders - and, last but not least, have more capacity. You can imagine that - the value reported by the drive when inquiring about the geometry - now becomes suspect at best, and nearly always misleading. When - asked for a geometry , it is nearly always better to supply the - geometry used by the BIOS, or <emphasis>if the BIOS is never going - to know about this disk</emphasis>, (e.g. it is not a booting - disk) to supply a fictitious geometry that is convenient.</para> - </sect4> - - <sect4> - <title>SCSI subsystem design</title> - - <para>FreeBSD uses a layered SCSI subsystem. For each different - controller card a device driver is written. This driver knows all - the intimate details about the hardware it controls. The driver - has a interface to the upper layers of the SCSI subsystem through - which it receives its commands and reports back any status.</para> - - <para>On top of the card drivers there are a number of more generic - drivers for a class of devices. More specific: a driver for tape - devices (abbreviation: st), magnetic disks (sd), CD-ROMs (cd) etc. - In case you are wondering where you can find this stuff, it all - lives in <filename>/sys/scsi</filename>. See the man pages in - section 4 for more details.</para> - - <para>The multi level design allows a decoupling of low-level bit - banging and more high level stuff. Adding support for another - piece of hardware is a much more manageable problem.</para> - </sect4> - - <sect4> - <title>Kernel configuration</title> - - <para>Dependent on your hardware, the kernel configuration file must - contain one or more lines describing your host adapter(s). This - includes I/O addresses, interrupts etc. Consult the man page for - your adapter driver to get more info. Apart from that, check out - <filename>/sys/i386/conf/LINT</filename> for an overview of a - kernel config file. <filename>LINT</filename> contains every - possible option you can dream of. It does - <emphasis>not</emphasis> imply <filename>LINT</filename> will - actually get you to a working kernel at all.</para> - - <para>Although it is probably stating the obvious: the kernel config - file should reflect your actual hardware setup. So, interrupts, - I/O addresses etc must match the kernel config file. During - system boot messages will be displayed to indicate whether the - configured hardware was actually found.</para> - - <note> - <para>Note that most of the EISA/PCI drivers (namely - <devicename>ahb</devicename>, <devicename>ahc</devicename>, - <devicename>ncr</devicename> and <devicename>amd</devicename> - will automatically obtain the correct parameters from the host - adapters themselves at boot time; thus, you just need to write, - for instance, <literal>controller ahc0</literal>.</para> - </note> - - <para>An example loosely based on the FreeBSD 2.2.5-Release kernel - config file <filename>LINT</filename> with some added comments - (between []):</para> - - <programlisting> -# SCSI host adapters: `aha', `ahb', `aic', `bt', `nca' -# -# aha: Adaptec 154x -# ahb: Adaptec 174x -# ahc: Adaptec 274x/284x/294x -# aic: Adaptec 152x and sound cards using the Adaptec AIC-6360 (slow!) -# amd: AMD 53c974 based SCSI cards (e.g., Tekram DC-390 and 390T) -# bt: Most Buslogic controllers -# nca: ProAudioSpectrum cards using the NCR 5380 or Trantor T130 -# ncr: NCR/Symbios 53c810/815/825/875 etc based SCSI cards -# uha: UltraStore 14F and 34F -# sea: Seagate ST01/02 8 bit controller (slow!) -# wds: Western Digital WD7000 controller (no scatter/gather!). -# - -[For an Adaptec AHA274x/284x/294x/394x etc controller] -controller ahc0 - -[For an NCR/Symbios 53c875 based controller] -controller ncr0 - -[For an Ultrastor adapter] -controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr - -# Map SCSI buses to specific SCSI adapters -controller scbus0 at ahc0 -controller scbus2 at ncr0 -controller scbus1 at uha0 - -# The actual SCSI devices -disk sd0 at scbus0 target 0 unit 0 [SCSI disk 0 is at scbus 0, LUN 0] -disk sd1 at scbus0 target 1 [implicit LUN 0 if omitted] -disk sd2 at scbus1 target 3 [SCSI disk on the uha0] -disk sd3 at scbus2 target 4 [SCSI disk on the ncr0] -tape st1 at scbus0 target 6 [SCSI tape at target 6] -device cd0 at scbus? [the first ever CD-ROM found, no wiring]</programlisting> - - <para>The example above tells the kernel to look for a ahc (Adaptec - 274x) controller, then for an NCR/Symbios board, and so on. The - lines following the controller specifications tell the kernel to - configure specific devices but <emphasis>only</emphasis> attach - them when they match the target ID and LUN specified on the - corresponding bus.</para> - - <para>Wired down devices get “first shot” at the unit - numbers so the first non “wired down” device, is - allocated the unit number one greater than the highest - “wired down” unit number for that kind of device. So, - if you had a SCSI tape at target ID 2 it would be configured as - st2, as the tape at target ID 6 is wired down to unit number - 1.</para> - - <note> - <para>Wired down devices need not be found to get their unit - number. The unit number for a wired down device is reserved for - that device, even if it is turned off at boot time. This allows - the device to be turned on and brought on-line at a later time, - without rebooting. Notice that a device's unit number has - <emphasis>no</emphasis> relationship with its target ID on the - SCSI bus.</para> - </note> - - <para>Below is another example of a kernel config file as used by - FreeBSD version < 2.0.5. The difference with the first example - is that devices are not “wired down”. “Wired - down” means that you specify which SCSI target belongs to - which device.</para> - - <para>A kernel built to the config file below will attach the first - SCSI disk it finds to sd0, the second disk to sd1 etc. If you ever - removed or added a disk, all other devices of the same type (disk - in this case) would 'move around'. This implies you have to - change <filename>/etc/fstab</filename> each time.</para> - - <para>Although the old style still works, you are - <emphasis>strongly</emphasis> recommended to use this new feature. - It will save you a lot of grief whenever you shift your hardware - around on the SCSI buses. So, when you re-use your old trusty - config file after upgrading from a pre-FreeBSD2.0.5.R system check - this out.</para> - - <programlisting> -[driver for Adaptec 174x] -controller ahb0 at isa? bio irq 11 vector ahbintr - -[for Adaptec 154x] -controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr - -[for Seagate ST01/02] -controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr - -controller scbus0 - -device sd0 [support for 4 SCSI harddisks, sd0 up sd3] -device st0 [support for 2 SCSI tapes] - -[for the CD-ROM] -device cd0 #Only need one of these, the code dynamically grows</programlisting> - - <para>Both examples support SCSI disks. If during boot more devices - of a specific type (e.g. sd disks) are found than are configured - in the booting kernel, the system will simply allocate more - devices, incrementing the unit number starting at the last number - “wired down”. If there are no “wired - down” devices then counting starts at unit 0.</para> - - <para>Use <command>man 4 scsi</command> to check for the latest info - on the SCSI subsystem. For more detailed info on host adapter - drivers use eg <command>man 4 ahc</command> for info on the - Adaptec 294x driver.</para> - </sect4> - - <sect4> - <title>Tuning your SCSI kernel setup</title> - - <para>Experience has shown that some devices are slow to respond to - INQUIRY commands after a SCSI bus reset (which happens at boot - time). An INQUIRY command is sent by the kernel on boot to see - what kind of device (disk, tape, CD-ROM etc) is connected to a - specific target ID. This process is called device probing by the - way.</para> - - <para>To work around the 'slow response' problem, FreeBSD allows a - tunable delay time before the SCSI devices are probed following a - SCSI bus reset. You can set this delay time in your kernel - configuration file using a line like:</para> - - <programlisting> -options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device</programlisting> - - <para>This line sets the delay time to 15 seconds. On my own system - I had to use 3 seconds minimum to get my trusty old CD-ROM drive - to be recognized. Start with a high value (say 30 seconds or so) - when you have problems with device recognition. If this helps, - tune it back until it just stays working.</para> - </sect4> - - <sect4 id="scsi-rogue-devices"> - <title>Rogue SCSI devices</title> - - <para>Although the SCSI standard tries to be complete and concise, - it is a complex standard and implementing things correctly is no - easy task. Some vendors do a better job then others.</para> - - <para>This is exactly where the “rogue” devices come - into view. Rogues are devices that are recognized by the FreeBSD - kernel as behaving slightly (...) non-standard. Rogue devices are - reported by the kernel when booting. An example for two of my - cartridge tape units:</para> - - <screen>Feb 25 21:03:34 yedi /kernel: ahb0 targ 5 lun 0: <TANDBERG TDC 3600 -06:> -Feb 25 21:03:34 yedi /kernel: st0: Tandberg tdc3600 is a known rogue - -Mar 29 21:16:37 yedi /kernel: aha0 targ 5 lun 0: <ARCHIVE VIPER 150 21247-005> -Mar 29 21:16:37 yedi /kernel: st1: Archive Viper 150 is a known rogue </screen> - - <para>For instance, there are devices that respond to all LUNs on a - certain target ID, even if they are actually only one device. It - is easy to see that the kernel might be fooled into believing that - there are 8 LUNs at that particular target ID. The confusion this - causes is left as an exercise to the reader.</para> - - <para>The SCSI subsystem of FreeBSD recognizes devices with bad - habits by looking at the INQUIRY response they send when probed. - Because the INQUIRY response also includes the version number of - the device firmware, it is even possible that for different - firmware versions different workarounds are used. See e.g. - <filename>/sys/scsi/st.c</filename> and - <filename>/sys/scsi/scsiconf.c</filename> for more info on how - this is done.</para> - - <para>This scheme works fine, but keep in mind that it of course - only works for devices that are known to be weird. If you are the - first to connect your bogus Mumbletech SCSI CD-ROM you might be - the one that has to define which workaround is needed.</para> - - <para>After you got your Mumbletech working, please send the - required workaround to the FreeBSD development team for inclusion - in the next release of FreeBSD. Other Mumbletech owners will be - grateful to you.</para> - </sect4> - - <sect4> - <title>Multiple LUN devices</title> - - <para>In some cases you come across devices that use multiple - logical units (LUNs) on a single SCSI ID. In most cases FreeBSD - only probes devices for LUN 0. An example are so called bridge - boards that connect 2 non-SCSI harddisks to a SCSI bus (e.g. an - Emulex MD21 found in old Sun systems).</para> - - <para>This means that any devices with LUNs != 0 are not normally - found during device probe on system boot. To work around this - problem you must add an appropriate entry in /sys/scsi/scsiconf.c - and rebuild your kernel.</para> - - <para>Look for a struct that is initialized like below:</para> - - <programlisting> -{ - T_DIRECT, T_FIXED, "MAXTOR", "XT-4170S", "B5A", - "mx1", SC_ONE_LU -}</programlisting> - - <para>For you Mumbletech BRIDGE2000 that has more than one LUN, acts - as a SCSI disk and has firmware revision 123 you would add - something like:</para> - - <programlisting> -{ - T_DIRECT, T_FIXED, "MUMBLETECH", "BRIDGE2000", "123", - "sd", SC_MORE_LUS -}</programlisting> - - <para>The kernel on boot scans the inquiry data it receives against - the table and acts accordingly. See the source for more - info.</para> - </sect4> - - <sect4> - <title>Tagged command queueing</title> - - <para>Modern SCSI devices, particularly magnetic disks, - support what is called tagged command queuing (TCQ).</para> - - <para>In a nutshell, TCQ allows the device to have multiple I/O - requests outstanding at the same time. Because the device is - intelligent, it can optimise its operations (like head - positioning) based on its own request queue. On SCSI devices - like RAID (Redundant Array of Independent Disks) arrays the TCQ - function is indispensable to take advantage of the device's - inherent parallelism.</para> - - <para>Each I/O request is uniquely identified by a “tag” - (hence the name tagged command queuing) and this tag is used by - FreeBSD to see which I/O in the device drivers queue is reported - as complete by the device.</para> - - <para>It should be noted however that TCQ requires device driver - support and that some devices implemented it “not quite - right” in their firmware. This problem bit me once, and it - leads to highly mysterious problems. In such cases, try to - disable TCQ.</para> - </sect4> - - <sect4> - <title>Busmaster host adapters</title> - - <para>Most, but not all, SCSI host adapters are bus mastering - controllers. This means that they can do I/O on their own without - putting load onto the host CPU for data movement.</para> - - <para>This is of course an advantage for a multitasking operating - system like FreeBSD. It must be noted however that there might be - some rough edges.</para> - - <para>For instance an Adaptec 1542 controller can be set to use - different transfer speeds on the host bus (ISA or AT in this - case). The controller is settable to different rates because not - all motherboards can handle the higher speeds. Problems like - hangups, bad data etc might be the result of using a higher data - transfer rate then your motherboard can stomach.</para> - - <para>The solution is of course obvious: switch to a lower data - transfer rate and try if that works better.</para> - - <para>In the case of a Adaptec 1542, there is an option that can be - put into the kernel config file to allow dynamic determination of - the right, read: fastest feasible, transfer rate. This option is - disabled by default:</para> - - <programlisting> -options "TUNE_1542" #dynamic tune of bus DMA speed</programlisting> - - <para>Check the man pages for the host adapter that you use. Or - better still, use the ultimate documentation (read: driver - source).</para> - </sect4> - </sect3> - - <sect3> - <title>Tracking down problems</title> - - <para>The following list is an attempt to give a guideline for the - most common SCSI problems and their solutions. It is by no means - complete.</para> - - <itemizedlist> - <listitem> - <para>Check for loose connectors and cables.</para> - </listitem> - - <listitem> - <para>Check and double check the location and number of your - terminators.</para> - </listitem> - - <listitem> - <para>Check if your bus has at least one supplier of terminator - power (especially with external terminators.</para> - </listitem> - - <listitem> - <para>Check if no double target IDs are used.</para> - </listitem> - - <listitem> - <para>Check if all devices to be used are powered up.</para> - </listitem> - - <listitem> - <para>Make a minimal bus config with as little devices as - possible.</para> - </listitem> - - <listitem> - <para>If possible, configure your host adapter to use slow bus - speeds.</para> - </listitem> - - <listitem> - <para>Disable tagged command queuing to make things as simple as - possible (for a NCR hostadapter based system see man - ncrcontrol)</para> - </listitem> - - <listitem> - <para>If you can compile a kernel, make one with the - <literal>SCSIDEBUG</literal> option, and try accessing the - device with debugging turned on for that device. If your device - does not even probe at startup, you may have to define the - address of the device that is failing, and the desired debug - level in <filename>/sys/scsi/scsidebug.h</filename>. If it - probes but just does not work, you can use the - &man.scsi.8; command to dynamically set a debug level to - it in a running kernel (if <literal>SCSIDEBUG</literal> is - defined). This will give you <emphasis>copious</emphasis> - debugging output with which to confuse the gurus. See - <command>man 4 scsi</command> for more exact information. Also - look at <command>man 8 scsi</command>.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3 id="scsi-further-reading"> - <title>Further reading</title> - - <para>If you intend to do some serious SCSI hacking, you might want to - have the official standard at hand:</para> - - <para>Approved American National Standards can be purchased from - ANSI at - - <address> - <otheraddr>13th Floor</otheraddr> - <street>11 West 42nd Street</street> - <city>New York</city> - <state>NY</state> <postcode>10036</postcode> - Sales Dept: <phone>(212) 642-4900</phone> - </address> - </para> - - <para>You can also buy many ANSI - standards and most committee draft documents from Global - Engineering Documents, - - <address> - <street>15 Inverness Way East</street> - <city>Englewood</city> - <state>CO</state>, <postcode>80112-5704</postcode> - Phone: <phone>(800) 854-7179</phone> - Outside USA and Canada: <phone>(303) 792-2181</phone> - Fax: <fax>(303) 792- 2192</fax> - </address> - </para> - - <para>Many X3T10 draft documents are available electronically on the - SCSI BBS (719-574-0424) and on the <hostid - role="fqdn">ncrinfo.ncr.com</hostid> anonymous ftp site.</para> - - <para>Latest X3T10 committee documents are:</para> - - <itemizedlist> - <listitem> - <para>AT Attachment (ATA or IDE) [X3.221-1994] - (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>ATA Extensions (ATA-2) [X3T10/948D Rev 2i]</para> - </listitem> - - <listitem> - <para>Enhanced Small Device Interface (ESDI) - [X3.170-1990/X3.170a-1991] - (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>Small Computer System Interface — 2 (SCSI-2) - [X3.131-1994] (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>SCSI-2 Common Access Method Transport and SCSI Interface - Module (CAM) [X3T10/792D Rev 11]</para> - </listitem> - </itemizedlist> - - <para>Other publications that might provide you with additional - information are:</para> - - <itemizedlist> - <listitem> - <para>“SCSI: Understanding the Small Computer System - Interface”, written by NCR Corporation. Available from: - Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 - ISBN 0-13-796855-8</para> - </listitem> - - <listitem> - <para>“Basics of SCSI”, a SCSI tutorial written by - Ancot Corporation Contact Ancot for availability information at: - Phone: (415) 322-5322 Fax: (415) 322-0455</para> - </listitem> - - <listitem> - <para>“SCSI Interconnection Guide Book”, an AMP - publication (dated 4/93, Catalog 65237) that lists the various - SCSI connectors and suggests cabling schemes. Available from - AMP at (800) 522-6752 or (717) 564-0100</para> - </listitem> - - <listitem> - <para>“Fast Track to SCSI”, A Product Guide written by - Fujitsu. Available from: Prentice Hall, Englewood Cliffs, NJ, - 07632 Phone: (201) 767-5937 ISBN 0-13-307000-X</para> - </listitem> - - <listitem> - <para>“The SCSI Bench Reference”, “The SCSI - Encyclopedia”, and the “SCSI Tutor”, ENDL - Publications, 14426 Black Walnut Court, Saratoga CA, 95070 - Phone: (408) 867-6642</para> - </listitem> - - <listitem> - <para>“Zadian SCSI Navigator” (quick ref. book) and - “Discover the Power of SCSI” (First book along with - a one-hour video and tutorial book), Zadian Software, Suite 214, - 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800</para> - </listitem> - </itemizedlist> - - <para>On Usenet the newsgroups <ulink - URL="news:comp.periphs.scsi">comp.periphs.scsi</ulink> and <ulink - URL="news:comp.periphs">comp.periphs</ulink> are noteworthy places - to look for more info. You can also find the SCSI-Faq there, which - is posted periodically.</para> - - <para>Most major SCSI device and host adapter suppliers operate ftp - sites and/or BBS systems. They may be valuable sources of - information about the devices you own.</para> - </sect3> - </sect2> - - <sect2 id="hw-storage-controllers"> - <title>* Disk/tape controllers</title> - - <sect3> - <title>* SCSI</title> - - <para></para> - </sect3> - - <sect3> - <title>* IDE</title> - - <para></para> - </sect3> - - <sect3> - <title>* Floppy</title> - - <para></para> - </sect3> - </sect2> - - <sect2> - <title>Hard drives</title> - - <sect3> - <title>SCSI hard drives</title> - - <para><emphasis>Contributed by &a.asami;. 17 February - 1998.</emphasis></para> - - <para>As mentioned in the <link linkend="scsi">SCSI</link> section, - virtually all SCSI hard drives sold today are SCSI-2 compliant and - thus will work fine as long as you connect them to a supported SCSI - host adapter. Most problems people encounter are either due to - badly designed cabling (cable too long, star topology, etc.), - insufficient termination, or defective parts. Please refer to the - <link linkend="scsi">SCSI</link> section first if your SCSI hard - drive is not working. However, there are a couple of things you may - want to take into account before you purchase SCSI hard drives for - your system.</para> - - <sect4> - <title>Rotational speed</title> - - <para>Rotational speeds of SCSI drives sold today range from around - 4,500RPM to 10,000RPM. Most of them are either 5,400RPM or - 7,200RPM. Even though the 7,200RPM drives can generally transfer - data faster, they run considerably hotter than their 5,400RPM - counterparts. A large fraction of today's disk drive malfunctions - are heat-related. If you do not have very good cooling in your PC - case, you may want to stick with 5,400RPM or slower drives.</para> - - <para>Note that newer drives, with higher areal recording densities, - can deliver much more bits per rotation than older ones. Today's - top-of-line 5,400RPM drives can sustain a throughput comparable to - 7,200RPM drives of one or two model generations ago. The number - to find on the spec sheet for bandwidth is “internal data - (or transfer) rate”. It is usually in megabits/sec so - divide it by 8 and you'll get the rough approximation of how much - megabytes/sec you can get out of the drive.</para> - - <para>(If you are a speed maniac and want a 10,000RPM drive for your - cute little peecee, be my guest; however, those drives become - extremely hot. Don't even think about it if you don't have a fan - blowing air <emphasis>directly at</emphasis> the drive or a - properly ventilated disk enclosure.)</para> - - <para>Obviously, the latest 10,000RPM drives and 7,200RPM drives can - deliver more data than the latest 5,400RPM drives, so if absolute - bandwidth is the necessity for your applications, you have little - choice but to get the faster drives. Also, if you need low - latency, faster drives are better; not only do they usually have - lower average seek times, but also the rotational delay is one - place where slow-spinning drives can never beat a faster one. - (The average rotational latency is half the time it takes to - rotate the drive once; thus, it's 3 milliseconds for 10,000RPM - drives, 4.2ms for 7,200RPM drives and 5.6ms for 5,400RPM drives.) - Latency is seek time plus rotational delay. Make sure you - understand whether you need low latency or more accesses per - second, though; in the latter case (e.g., news servers), it may - not be optimal to purchase one big fast drive. You can achieve - similar or even better results by using the ccd (concatenated - disk) driver to create a striped disk array out of multiple slower - drives for comparable overall cost.</para> - - <para>Make sure you have adequate air flow around the drive, - especially if you are going to use a fast-spinning drive. You - generally need at least 1/2" (1.25cm) of spacing above and below a - drive. Understand how the air flows through your PC case. Most - cases have the power supply suck the air out of the back. See - where the air flows in, and put the drive where it will have the - largest volume of cool air flowing around it. You may need to seal - some unwanted holes or add a new fan for effective cooling.</para> - - <para>Another consideration is noise. Many 7,200 or faster drives - generate a high-pitched whine which is quite unpleasant to most - people. That, plus the extra fans often required for cooling, may - make 7,200 or faster drives unsuitable for some office and home - environments.</para> - </sect4> - - <sect4> - <title>Form factor</title> - - <para>Most SCSI drives sold today are of 3.5" form factor. They - come in two different heights; 1.6" (“half-height”) or - 1" (“low-profile”). The half-height drive is the same - height as a CD-ROM drive. However, don't forget the spacing rule - mentioned in the previous section. If you have three standard - 3.5" drive bays, you will not be able to put three half-height - drives in there (without frying them, that is).</para> - </sect4> - - <sect4> - <title>Interface</title> - - <para>The majority of SCSI hard drives sold today are Ultra or - Ultra-wide SCSI. The maximum bandwidth of Ultra SCSI is 20MB/sec, - and Ultra-wide SCSI is 40MB/sec. There is no difference in max - cable length between Ultra and Ultra-wide; however, the more - devices you have on the same bus, the sooner you will start having - bus integrity problems. Unless you have a well-designed disk - enclosure, it is not easy to make more than 5 or 6 Ultra SCSI - drives work on a single bus.</para> - - <para>On the other hand, if you need to connect many drives, going - for Fast-wide SCSI may not be a bad idea. That will have the same - max bandwidth as Ultra (narrow) SCSI, while electronically it's - much easier to get it “right”. My advice would be: if - you want to connect many disks, get wide SCSI drives; they usually - cost a little more but it may save you down the road. (Besides, - if you can't afford the cost difference, you shouldn't be building - a disk array.)</para> - - <para>There are two variant of wide SCSI drives; 68-pin and 80-pin - SCA (Single Connector Attach). The SCA drives don't have a - separate 4-pin power connector, and also read the SCSI ID settings - through the 80-pin connector. If you are really serious about - building a large storage system, get SCA drives and a good SCA - enclosure (dual power supply with at least one extra fan). They - are more electronically sound than 68-pin counterparts because - there is no “stub” of the SCSI bus inside the disk - canister as in arrays built from 68-pin drives. They are easier - to install too (you just need to screw the drive in the canister, - instead of trying to squeeze in your fingers in a tight place to - hook up all the little cables (like the SCSI ID and disk activity - LED lines).</para> - </sect4> - </sect3> - - <sect3> - <title>* IDE hard drives</title> - - <para></para> - </sect3> - </sect2> - - <sect2> - <title>Tape drives</title> - - <para><emphasis>Contributed by &a.jmb;. 2 July - 1996.</emphasis></para> - - <sect3> - <title>General tape access commands</title> - - <para>&man.mt.1; provides generic access to the tape drives. Some of - the more common commands are <command>rewind</command>, - <command>erase</command>, and <command>status</command>. See the - &man.mt.1; manual page for a detailed description.</para> - </sect3> - - <sect3> - <title>Controller Interfaces</title> - - <para>There are several different interfaces that support tape drives. - The interfaces are SCSI, IDE, Floppy and Parallel Port. A wide - variety of tape drives are available for these interfaces. - Controllers are discussed in <link - linkend="hw-storage-controllers">Disk/tape - controllers</link>.</para> - </sect3> - - <sect3> - <title>SCSI drives</title> - - <para>The &man.st.4; driver provides support for 8mm (Exabyte), 4mm - (DAT: Digital Audio Tape), QIC (Quarter-Inch Cartridge), DLT - (Digital Linear Tape), QIC Minicartridge and 9-track (remember the - big reels that you see spinning in Hollywood computer rooms) tape - drives. See the &man.st.4; manual page for a detailed - description.</para> - - <para>The drives listed below are currently being used by members of - the FreeBSD community. They are not the only drives that will work - with FreeBSD. They just happen to be the ones that we use.</para> - - <sect4> - <title>4mm (DAT: Digital Audio Tape)</title> - - <para><link linkend="hw-storage-python-28454">Archive Python - 28454</link></para> - - <para><link linkend="hw-storage-python-04687">Archive Python - 04687</link></para> - - <para><link linkend="hw-storage-hp1533a">HP C1533A</link></para> - - <para><link linkend="hw-storage-hp1534a">HP C1534A</link></para> - - <para><link linkend="hw-storage-hp35450a">HP 35450A</link></para> - - <para><link linkend="hw-storage-hp35470a">HP 35470A</link></para> - - <para><link linkend="hw-storage-hp35480a">HP 35480A</link></para> - - <para><link linkend="hw-storage-sdt5000">SDT-5000</link></para> - - <para><link linkend="hw-storage-wangtek6200">Wangtek - 6200</link></para> - </sect4> - - <sect4> - <title>8mm (Exabyte)</title> - - <para><link linkend="hw-storage-exb8200">EXB-8200</link></para> - - <para><link linkend="hw-storage-exb8500">EXB-8500</link></para> - - <para><link linkend="hw-storage-exb8505">EXB-8505</link></para> - </sect4> - - <sect4> - <title>QIC (Quarter-Inch Cartridge)</title> - - <para><link linkend="hw-storage-anaconda">Archive Ananconda - 2750</link></para> - - <para><link linkend="hw-storage-viper60">Archive Viper - 60</link></para> - - <para><link linkend="hw-storage-viper150">Archive Viper - 150</link></para> - - <para><link linkend="hw-storage-viper2525">Archive Viper - 2525</link></para> - - <para><link linkend="hw-storage-tandberg3600">Tandberg TDC - 3600</link></para> - - <para><link linkend="hw-storage-tandberg3620">Tandberg TDC - 3620</link></para> - - <para><link linkend="hw-storage-tandberg3800">Tandberg TDC - 3800</link></para> - - <para><link linkend="hw-storage-tandberg4222">Tandberg TDC - 4222</link></para> - - <para><link linkend="hw-storage-wangtek5525es">Wangtek - 5525ES</link></para> - </sect4> - - <sect4> - <title>DLT (Digital Linear Tape)</title> - - <para><link linkend="hw-storage-dectz87">Digital TZ87</link></para> - </sect4> - - <sect4> - <title>Mini-Cartridge</title> - - <para><link linkend="hw-storage-ctms3200">Conner CTMS - 3200</link></para> - - <para><link linkend="hw-storage-exb2501">Exabyte 2501</link></para> - </sect4> - - <sect4> - <title>Autoloaders/Changers</title> - - <para><link linkend="hw-storage-hp1553a">Hewlett-Packard HP C1553A - Autoloading DDS2</link></para> - </sect4> - </sect3> - - <sect3> - <title>* IDE drives</title> - - <para></para> - </sect3> - - <sect3> - <title>Floppy drives</title> - - <para><link linkend="hw-storage-conner420r">Conner 420R</link></para> - </sect3> - - <sect3> - <title>* Parallel port drives</title> - - <para></para> - </sect3> - - <sect3> - <title>Detailed Information</title> - - <sect4 id="hw-storage-anaconda"> - <title>Archive Anaconda 2750</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - ANCDA 2750 28077 -003 type 1 removable SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 1.35GB when using QIC-1350 tapes. This - drive will read and write QIC-150 (DC6150), QIC-250 (DC6250), and - QIC-525 (DC6525) tapes as well.</para> - - <para>Data transfer rate is 350kB/s using - &man.dump.8;. Rates of 530kB/s have been reported when using - <link linkend="backups-programs-amanda">Amanda</link></para> - - <para>Production of this drive has been discontinued.</para> - - <para>The SCSI bus connector on this tape drive is reversed from - that on most other SCSI devices. Make sure that you have enough - SCSI cable to twist the cable one-half turn before and after the - Archive Anaconda tape drive, or turn your other SCSI devices - upside-down.</para> - - <para>Two kernel code changes are required to use this drive. This - drive will not work as delivered.</para> - - <para>If you have a SCSI-2 controller, short jumper 6. Otherwise, - the drive behaves are a SCSI-1 device. When operating as a SCSI-1 - device, this drive, “locks” the SCSI bus during some - tape operations, including: fsf, rewind, and rewoffl.</para> - - <para>If you are using the NCR SCSI controllers, patch the file - <filename>/usr/src/sys/pci/ncr.c</filename> (as shown below). - Build and install a new kernel.</para> - - <programlisting> -*** 4831,4835 **** - }; - -! if (np->latetime>4) { - /* - ** Although we tried to wake it up, ---- 4831,4836 ---- - }; - -! if (np->latetime>1200) { - /* - ** Although we tried to wake it up,</programlisting> - - <para>Reported by: &a.jmb;</para> - </sect4> - - <sect4 id="hw-storage-python-28454"> - <title>Archive Python 28454</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - Python 28454-XXX4ASB</literal> <literal>type 1 removable SCSI - 2</literal> <literal>density code 0x8c, 512-byte - blocks</literal></para> - - <para>This is a DDS-1 tape drive.</para> - - <para>Native capacity is 2.5GB on 90m tapes.</para> - - <para>Data transfer rate is XXX.</para> - - <para>This drive was repackaged by Sun Microsystems as model - 595-3067.</para> - - <para>Reported by: Bob Bishop <email>rb@gid.co.uk</email></para> - - <para>Throughput is in the 1.5 MByte/sec range, however this will - drop if the disks and tape drive are on the same SCSI - controller.</para> - - <para>Reported by: Robert E. Seastrom - <email>rs@seastrom.com</email></para> - </sect4> - - <sect4 id="hw-storage-python-04687"> - <title>Archive Python 04687</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - Python 04687-XXX 6580</literal> <literal>Removable Sequential - Access SCSI-2 device</literal></para> - - <para>This is a DAT-DDS-2 drive.</para> - - <para>Native capacity is 4GB when using 120m tapes.</para> - - <para>This drive supports hardware data compression. Switch 4 - controls MRS (Media Recognition System). MRS tapes have stripes - on the transparent leader. Switch 4 <emphasis>off</emphasis> - enables MRS, <emphasis>on</emphasis> disables MRS.</para> - - <para>Parity is controlled by switch 5. Switch 5 - <emphasis>on</emphasis> to enable parity control. Compression is - enabled with Switch 6 <emphasis>off</emphasis>. It is possible to - override compression with the <literal>SCSI MODE SELECT</literal> - command (see &man.mt.1;).</para> - - <para>Data transfer rate is 800kB/s.</para> - </sect4> - - <sect4 id="hw-storage-viper60"> - <title>Archive Viper 60</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 60 21116 -007</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 60MB.</para> - - <para>Data transfer rate is XXX.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: Philippe Regnauld - <email>regnauld@hsc.fr</email></para> - </sect4> - - <sect4 id="hw-storage-viper150"> - <title>Archive Viper 150</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 150 21531 -004</literal> <literal>Archive Viper 150 is a - known rogue</literal> <literal>type 1 removable SCSI - 1</literal>. A multitude of firmware revisions exist for this - drive. Your drive may report different numbers (e.g - <literal>21247 -005</literal>.</para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 150/250MB. Both 150MB (DC6150) and 250MB - (DC6250) tapes have the recording format. The 250MB tapes are - approximately 67% longer than the 150MB tapes. This drive can - read 120MB tapes as well. It can not write 120MB tapes.</para> - - <para>Data transfer rate is 100kB/s</para> - - <para>This drive reads and writes DC6150 (150MB) and DC6250 (250MB) - tapes.</para> - - <para>This drives quirks are known and pre-compiled into the scsi - tape device driver (&man.st.4;).</para> - - <para>Under FreeBSD 2.2-current, use <command>mt blocksize - 512</command> to set the blocksize. (The particular drive had - firmware revision 21247 -005. Other firmware revisions may behave - differently) Previous versions of FreeBSD did not have this - problem.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: Pedro A M Vazquez - <email>vazquez@IQM.Unicamp.BR</email></para> - - <para>Mike Smith - <email>msmith@atrad.adelaide.edu.au</email></para> - </sect4> - - <sect4 id="hw-storage-viper2525"> - <title>Archive Viper 2525</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 2525 25462 -011</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Data transfer rate is 180kB/s at 90 inches/sec.</para> - - <para>The drive reads QIC-525, QIC-150, QIC-120 and QIC-24 tapes. - Writes QIC-525, QIC-150, and QIC-120.</para> - - <para>Firmware revisions prior to <literal>25462 -011</literal> are - bug ridden and will not function properly.</para> - - <para>Production of this drive has been discontinued.</para> - </sect4> - - <sect4 id="hw-storage-conner420r"> - <title>Conner 420R</title> - - <para>The boot message identifier for this drive is <literal>Conner - tape</literal>.</para> - - <para>This is a floppy controller, minicartridge tape drive.</para> - - <para>Native capacity is XXXX</para> - - <para>Data transfer rate is XXX</para> - - <para>The drive uses QIC-80 tape cartridges.</para> - - <para>Reported by: Mark Hannon - <email>mark@seeware.DIALix.oz.au</email></para> - </sect4> - - <sect4 id="hw-storage-ctms3200"> - <title>Conner CTMS 3200</title> - - <para>The boot message identifier for this drive is <literal>CONNER - CTMS 3200 7.00</literal> <literal>type 1 removable SCSI - 2</literal>.</para> - - <para>This is a minicartridge tape drive.</para> - - <para>Native capacity is XXXX</para> - - <para>Data transfer rate is XXX</para> - - <para>The drive uses QIC-3080 tape cartridges.</para> - - <para>Reported by: Thomas S. Traylor - <email>tst@titan.cs.mci.com</email></para> - </sect4> - - <sect4 id="hw-storage-dectz87"> - <title><ulink - URL="http://www.digital.com/info/Customer-Update/931206004.txt.html">DEC TZ87</ulink></title> - - <para>The boot message identifier for this drive is <literal>DEC - TZ87 (C) DEC 9206</literal> <literal>type 1 removable SCSI - 2</literal> <literal>density code 0x19</literal></para> - - <para>This is a DLT tape drive.</para> - - <para>Native capacity is 10GB.</para> - - <para>This drive supports hardware data compression.</para> - - <para>Data transfer rate is 1.2MB/s.</para> - - <para>This drive is identical to the Quantum DLT2000. The drive - firmware can be set to emulate several well-known drives, - including an Exabyte 8mm drive.</para> - - <para>Reported by: &a.wilko;</para> - </sect4> - - <sect4 id="hw-storage-exb2501"> - <title><ulink - URL="http://www.Exabyte.COM:80/Products/Minicartridge/2501/Rfeatures.html">Exabyte EXB-2501</ulink></title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-2501</literal></para> - - <para>This is a mini-cartridge tape drive.</para> - - <para>Native capacity is 1GB when using MC3000XL - minicartridges.</para> - - <para>Data transfer rate is XXX</para> - - <para>This drive can read and write DC2300 (550MB), DC2750 (750MB), - MC3000 (750MB), and MC3000XL (1GB) minicartridges.</para> - - <para>WARNING: This drive does not meet the SCSI-2 specifications. - The drive locks up completely in response to a SCSI MODE_SELECT - command unless there is a formatted tape in the drive. Before - using this drive, set the tape blocksize with</para> - - <screen>&prompt.root; <userinput>mt -f /dev/st0ctl.0 blocksize 1024</userinput></screen> - - <para>Before using a minicartridge for the first time, the - minicartridge must be formated. FreeBSD 2.1.0-RELEASE and - earlier:</para> - - <screen>&prompt.root; <userinput>/sbin/scsi -f /dev/rst0.ctl -s 600 -c "4 0 0 0 0 0"</userinput></screen> - - <para>(Alternatively, fetch a copy of the - <command>scsiformat</command> shell script from FreeBSD - 2.1.5/2.2.) FreeBSD 2.1.5 and later:</para> - - <screen>&prompt.root; <userinput>/sbin/scsiformat -q -w /dev/rst0.ctl</userinput></screen> - - <para>Right now, this drive cannot really be recommended for - FreeBSD.</para> - - <para>Reported by: Bob Beaulieu - <email>ez@eztravel.com</email></para> - </sect4> - - <sect4 id="hw-storage-exb8200"> - <title>Exabyte EXB-8200</title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-8200 252X</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is an 8mm tape drive.</para> - - <para>Native capacity is 2.3GB.</para> - - <para>Data transfer rate is 270kB/s.</para> - - <para>This drive is fairly slow in responding to the SCSI bus during - boot. A custom kernel may be required (set SCSI_DELAY to 10 - seconds).</para> - - <para>There are a large number of firmware configurations for this - drive, some have been customized to a particular vendor's - hardware. The firmware can be changed via EPROM - replacement.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: Mike Smith - <email>msmith@atrad.adelaide.edu.au</email></para> - </sect4> - - <sect4 id="hw-storage-exb8500"> - <title>Exabyte EXB-8500</title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-8500-85Qanx0 0415</literal> <literal>type 1 removable SCSI - 2</literal></para> - - <para>This is an 8mm tape drive.</para> - - <para>Native capacity is 5GB.</para> - - <para>Data transfer rate is 300kB/s.</para> - - <para>Reported by: Greg Lehey <email>grog@lemis.de</email></para> - </sect4> - - <sect4 id="hw-storage-exb8505"> - <title><ulink - URL="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">Exabyte EXB-8505</ulink></title> - - <para>The boot message identifier for this drive is - <literal>EXABYTE EXB-85058SQANXR1 05B0</literal> <literal>type 1 - removable SCSI 2</literal></para> - - <para>This is an 8mm tape drive which supports compression, and is - upward compatible with the EXB-5200 and EXB-8500.</para> - - <para>Native capacity is 5GB.</para> - - <para>The drive supports hardware data compression.</para> - - <para>Data transfer rate is 300kB/s.</para> - - <para>Reported by: Glen Foster - <email>gfoster@gfoster.com</email></para> - </sect4> - - <sect4 id="hw-storage-hp1533a"> - <title>Hewlett-Packard HP C1533A</title> - - <para>The boot message identifier for this drive is <literal>HP - C1533A 9503</literal> <literal>type 1 removable SCSI - 2</literal>.</para> - - <para>This is a DDS-2 tape drive. DDS-2 means hardware data - compression and narrower tracks for increased data - capacity.</para> - - <para>Native capacity is 4GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is 510kB/s.</para> - - <para>This drive is used in Hewlett-Packard's SureStore 6000eU and - 6000i tape drives and C1533A DDS-2 DAT drive.</para> - - <para>The drive has a block of 8 dip switches. The proper settings - for FreeBSD are: 1 ON; 2 ON; 3 OFF; 4 ON; 5 ON; 6 ON; 7 ON; 8 - ON.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>switch 1</entry> - <entry>switch 2</entry> - <entry>Result</entry> - </row> - </thead> - - <tbody> - <row> - <entry>On</entry> - <entry>On</entry> - <entry>Compression enabled at power-on, with host - control</entry> - </row> - - <row> - <entry>On</entry> - <entry>Off</entry> - <entry>Compression enabled at power-on, no host - control</entry> - </row> - - <row> - <entry>Off</entry> - <entry>On</entry> - <entry>Compression disabled at power-on, with host - control</entry> - </row> - - <row> - <entry>Off</entry> - <entry>Off</entry> - <entry>Compression disabled at power-on, no host - control</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Switch 3 controls MRS (Media Recognition System). MRS tapes - have stripes on the transparent leader. These identify the tape - as DDS (Digital Data Storage) grade media. Tapes that do not have - the stripes will be treated as write-protected. Switch 3 OFF - enables MRS. Switch 3 ON disables MRS.</para> - - <para>See <ulink URL="http://www.hp.com/tape/c_intro.html">HP - SureStore Tape Products</ulink> and <ulink - URL="http://www.impediment.com/hp/hp_technical.html">Hewlett-Packard - Disk and Tape Technical Information</ulink> for more information - on configuring this drive.</para> - - <para><emphasis>Warning:</emphasis> Quality control on these drives - varies greatly. One FreeBSD core-team member has returned 2 of - these drives. Neither lasted more than 5 months.</para> - - <para>Reported by: &a.se;</para> - </sect4> - - <sect4 id="hw-storage-hp1534a"> - <title>Hewlett-Packard HP 1534A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35470A T503</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code 0x13, - variable blocks</literal>.</para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 2GB when using 90m tapes.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>The same mechanism is used in Hewlett-Packard's SureStore - <ulink URL="http://www.dmo.hp.com/tape/sst2000.htm">2000i</ulink> - tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT - drive and HP C1536A DDS format DAT drive.</para> - - <para>The HP C1534A DDS format DAT drive has two indicator lights, - one green and one amber. The green one indicates tape action: - slow flash during load, steady when loaded, fast flash during - read/write operations. The amber one indicates warnings: slow - flash when cleaning is required or tape is nearing the end of its - useful life, steady indicates an hard fault. (factory service - required?)</para> - - <para>Reported by Gary Crutcher - <email>gcrutchr@nightflight.com</email></para> - </sect4> - - <sect4 id="hw-storage-hp1553a"> - <title>Hewlett-Packard HP C1553A Autoloading DDS2</title> - - <para>The boot message identifier for this drive is "".</para> - - <para>This is a DDS-2 tape drive with a tape changer. DDS-2 means - hardware data compression and narrower tracks for increased data - capacity.</para> - - <para>Native capacity is 24GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is 510kB/s (native).</para> - - <para>This drive is used in Hewlett-Packard's SureStore <ulink - URL="http://www.dmo.hp.com/tape/sst12000.htm">12000e</ulink> - tape drive.</para> - - <para>The drive has two selectors on the rear panel. The selector - closer to the fan is SCSI id. The other selector should be set to - 7.</para> - - <para>There are four internal switches. These should be set: 1 ON; - 2 ON; 3 ON; 4 OFF.</para> - - <para>At present the kernel drivers do not automatically change - tapes at the end of a volume. This shell script can be used to - change tapes:</para> - - <programlisting> -#!/bin/sh -PATH="/sbin:/usr/sbin:/bin:/usr/bin"; export PATH - -usage() -{ - echo "Usage: dds_changer [123456ne] raw-device-name - echo "1..6 = Select cartridge" - echo "next cartridge" - echo "eject magazine" - exit 2 -} - -if [ $# -ne 2 ] ; then - usage -fi - -cdb3=0 -cdb4=0 -cdb5=0 - -case $1 in - [123456]) - cdb3=$1 - cdb4=1 - ;; - n) - ;; - e) - cdb5=0x80 - ;; - ?) - usage - ;; -esac - -scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5"</programlisting> - </sect4> - - <sect4 id="hw-storage-hp35450a"> - <title>Hewlett-Packard HP 35450A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35450A -A C620</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 1.2GB.</para> - - <para>Data transfer rate is 160kB/s.</para> - - <para>Reported by: mark thompson - <email>mark.a.thompson@pobox.com</email></para> - </sect4> - - <sect4 id="hw-storage-hp35470a"> - <title>Hewlett-Packard HP 35470A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35470A 9 09</literal> <literal>type 1 removable SCSI - 2</literal></para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 2GB when using 90m tapes.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>The same mechanism is used in Hewlett-Packard's SureStore - <ulink URL="http://www.dmo.hp.com/tape/sst2000.htm">2000i</ulink> - tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT - drive, and HP C1536A DDS format DAT drive.</para> - - <para><emphasis>Warning:</emphasis> Quality control on these drives - varies greatly. One FreeBSD core-team member has returned 5 of - these drives. None lasted more than 9 months.</para> - - <para>Reported by: David Dawes - <email>dawes@rf900.physics.usyd.edu.au</email> (9 09)</para> - - </sect4> - - <sect4 id="hw-storage-hp35480a"> - <title>Hewlett-Packard HP 35480A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35480A 1009</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal>.</para> - - <para>This is a DDS-DC tape drive. DDS-DC is DDS-1 with hardware - data compression. DDS-1 is the original DAT tape format.</para> - - <para>Native capacity is 2GB when using 90m tapes. It cannot handle - 120m tapes. This drive supports hardware data compression. - Please refer to the section on <link - linkend="hw-storage-hp1533a">HP C1533A</link> for the proper - switch settings.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>This drive is used in Hewlett-Packard's SureStore <ulink - URL="http://www.dmo.hp.com/tape/sst5000.htm">5000eU</ulink> and - <ulink URL="http://www.dmo.hp.com/tape/sst5000.htm">5000i</ulink> - tape drives and C35480A DDS format DAT drive..</para> - - <para>This drive will occasionally hang during a tape eject - operation (<command>mt offline</command>). Pressing the front - panel button will eject the tape and bring the tape drive back to - life.</para> - - <para>WARNING: HP 35480-03110 only. On at least two occasions this - tape drive when used with FreeBSD 2.1.0, an IBM Server 320 and an - 2940W SCSI controller resulted in all SCSI disk partitions being - lost. The problem has not be analyzed or resolved at this - time.</para> - </sect4> - - <sect4 id="hw-storage-sdt5000"> - <title><ulink - URL="http://www.sel.sony.com/SEL/ccpg/storage/tape/t5000.html">Sony SDT-5000</ulink></title> - - <para>There are at least two significantly different models: one is - a DDS-1 and the other DDS-2. The DDS-1 version is - <literal>SDT-5000 3.02</literal>. The DDS-2 version is - <literal>SONY SDT-5000 327M</literal>. The DDS-2 version has a 1MB - cache. This cache is able to keep the tape streaming in almost - any circumstances.</para> - - <para>The boot message identifier for this drive is <literal>SONY - SDT-5000 3.02</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>Native capacity is 4GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is depends upon the model or the drive. The - rate is 630kB/s for the <literal>SONY SDT-5000 327M</literal> - while compressing the data. For the <literal>SONY SDT-5000 - 3.02</literal>, the data transfer rate is 225kB/s.</para> - - <para>In order to get this drive to stream, set the blocksize to 512 - bytes (<command>mt blocksize 512</command>) reported by Kenneth - Merry ken@ulc199.residence.gatech.edu</para> - - <para><literal>SONY SDT-5000 327M</literal> information reported by - Charles Henrich henrich@msu.edu</para> - - <para>Reported by: &a.jmz;</para> - </sect4> - - <sect4 id="hw-storage-tandberg3600"> - <title>Tandberg TDC 3600</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 3600 =08:</literal> <literal>type 1 - removable SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 150/250MB.</para> - - <para>This drive has quirks which are known and work around code is - present in the scsi tape device driver (&man.st.4;). - Upgrading the firmware to XXX version will fix the quirks and - provide SCSI 2 capabilities.</para> - - <para>Data transfer rate is 80kB/s.</para> - - <para>IBM and Emerald units will not work. Replacing the firmware - EPROM of these units will solve the problem.</para> - - <para>Reported by: Michael Smith - <email>msmith@atrad.adelaide.edu.au</email></para> - </sect4> - - <sect4 id="hw-storage-tandberg3620"> - <title>Tandberg TDC 3620</title> - - <para>This is very similar to the <link - linkend="hw-storage-tandberg3600">Tandberg TDC 3600</link> - drive.</para> - - <para>Reported by: &a.joerg;</para> - </sect4> - - <sect4 id="hw-storage-tandberg3800"> - <title>Tandberg TDC 3800</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 3800 =04Y</literal> <literal>Removable - Sequential Access SCSI-2 device</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Reported by: &a.jhs;</para> - </sect4> - - <sect4 id="hw-storage-tandberg4222"> - <title>Tandberg TDC 4222</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 4222 =07</literal> <literal>type 1 removable - SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 2.5GB. The drive will read all cartridges - from the 60 MB (DC600A) upwards, and write 150 MB (DC6150) - upwards. Hardware compression is optionally supported for the 2.5 - GB cartridges.</para> - - <para>This drives quirks are known and pre-compiled into the scsi - tape device driver (&man.st.4;) beginning with FreeBSD - 2.2-current. For previous versions of FreeBSD, use - <command>mt</command> to read one block from the tape, rewind the - tape, and then execute the backup program (<command>mt fsr 1; mt - rewind; dump ...</command>)</para> - - <para>Data transfer rate is 600kB/s (vendor claim with compression), - 350 KB/s can even be reached in start/stop mode. The rate - decreases for smaller cartridges.</para> - - <para>Reported by: &a.joerg;</para> - </sect4> - - <sect4 id="hw-storage-wangtek5525es"> - <title>Wangtek 5525ES</title> - - <para>The boot message identifier for this drive is <literal>WANGTEK - 5525ES SCSI REV7 3R1</literal> <literal>type 1 removable SCSI - 1</literal> <literal>density code 0x11, 1024-byte - blocks</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Data transfer rate is 180kB/s.</para> - - <para>The drive reads 60, 120, 150, and 525MB tapes. The drive will - not write 60MB (DC600 cartridge) tapes. In order to overwrite 120 - and 150 tapes reliably, first erase (<command>mt erase</command>) - the tape. 120 and 150 tapes used a wider track (fewer tracks per - tape) than 525MB tapes. The “extra” width of the - previous tracks is not overwritten, as a result the new data lies - in a band surrounded on both sides by the previous data unless the - tape have been erased.</para> - - <para>This drives quirks are known and pre-compiled into the scsi - tape device driver (&man.st.4;).</para> - - <para>Other firmware revisions that are known to work are: - M75D</para> - - <para>Reported by: Marc van Kempen <email>marc@bowtie.nl</email> - <literal>REV73R1</literal> Andrew Gordon - <email>Andrew.Gordon@net-tel.co.uk</email> - <literal>M75D</literal></para> - </sect4> - - <sect4 id="hw-storage-wangtek6200"> - <title>Wangtek 6200</title> - - <para>The boot message identifier for this drive is <literal>WANGTEK - 6200-HS 4B18</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>This is a DDS-1 tape drive.</para> - - <para>Native capacity is 2GB using 90m tapes.</para> - - <para>Data transfer rate is 150kB/s.</para> - - <para>Reported by: Tony Kimball <email>alk@Think.COM</email></para> - </sect4> - </sect3> - - <sect3> - <title>* Problem drives</title> - - <para></para> - </sect3> - </sect2> - - <sect2> - <title>CD-ROM drives</title> - - <para><emphasis>Contributed by &a.obrien;. 23 November - 1997.</emphasis></para> - - <para>As mentioned in <link linkend="hw-jordans-picks-cdrom">Jordan's - Picks</link> Generally speaking those in <emphasis>The FreeBSD - Project</emphasis> prefer SCSI CDROM drives over IDE CDROM drives. - However not all SCSI CDROM drives are equal. Some feel the quality of - some SCSI CDROM drives have been deteriorating to that of IDE CDROM - drives. Toshiba used to be the favored stand-by, but many on the SCSI - mailing list have found displeasure with the 12x speed XM-5701TA as - its volume (when playing audio CDROMs) is not controllable by the - various audio player software.</para> - - <para>Another area where SCSI CDROM manufacturers are cutting corners is - adherence to the <link linkend="scsi-further-reading">SCSI - specification</link>. Many SCSI CDROMs will respond to <link - linkend="scsi-rogue-devices">multiple LUNs</link> for its target - address. Known violators include the 6x Teac CD-56S 1.0D.</para> - </sect2> - - <sect2> - <title>* Other</title> - - <para></para> - </sect2> - </sect1> - - <sect1 id="hw-other"> - <title>* Other</title> - - - <sect2> - <title>* PCMCIA</title> - - <para></para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/install/chapter.sgml b/en/handbook/install/chapter.sgml deleted file mode 100644 index d30527f9bf..0000000000 --- a/en/handbook/install/chapter.sgml +++ /dev/null @@ -1,1307 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.21 1999-08-11 22:28:18 nik Exp $ ---> - -<chapter id="install"> - <title>Installing FreeBSD</title> - - <para>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.</para> - - <para>Regardless of the installation media you choose, you can get started - by creating the <emphasis>installation disks</emphasis> as described - below. Booting your computer into the FreeBSD installer, even if you - are not planning on installing FreeBSD right away, will provide important - information about compatibility between FreeBSD and your hardware which - may, in turn, dictate which installation options are even possible. It - can also provide early clues to any compatibility problems which could - prevent FreeBSD running on your system at all.</para> - - <para>If you plan on installing via anonymous FTP then the installation - floppies are all you need to download and create—the installation - program itself will handle any further required downloading directly - (using an ethernet connection, a modem and ppp dialip #, etc).</para> - - <para>For more information on obtaining the latest FreeBSD distributions, - please see <link linkend="mirrors">Obtaining FreeBSD</link> in the - Appendix.</para> - - <para>So, to get the show on the road, follow these steps:</para> - - <procedure> - <step> - <para>Review the <link linkend="install-hw">supported - configurations</link> 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.</para> - </step> - - <step> - <para>If you are installing FreeBSD from CDROM media then you have - several different installation options:</para> - - <itemizedlist> - <listitem> - <para>If the CD has been mastered with El Torrito boot support and - your system supports direct booting from CDROM (and many older - systems do <emphasis>not</emphasis>), simply insert the CD into - the drive and boot directly from it.</para> - </listitem> - - <listitem> - <para>If you are running DOS and have the proper drivers to access - your CD, run the install.bat script provided on the CD. This will - attempt to boot into the FreeBSD installation straight from - DOS.</para> - - <note> - <para>You must do this from actual DOS and not a Windows DOS - box.</para> - </note> - - <para>If you also want to install FreeBSD from your DOS partition - (perhaps because your CDROM drive is completely unsupported by - FreeBSD) then run the setup program first to copy the appropriate - files from the CD to your DOS partition, afterwards running - install.</para> - </listitem> - - <listitem> - <para>If either of the two proceeding methods work then you can - simply skip the rest of this section, otherwise your final option - is to create a set of boot floppies from the - <filename>floppies\kern.flp</filename> and - <filename>floppies\mfsroot.flp</filename> images—proceed to - step 4 for instructions on how to do this.</para> - </listitem> - </itemizedlist> - </step> - - <step> - <para>If you do not have a CDROM distribution then simply read the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/&rel.current;-RELEASE/floppies/README.TXT">installation - boot image information</ulink> to find out what files you need to - download first.</para> - </step> - - <step> - <para>Make the installation boot disks from the image files:</para> - - <itemizedlist> - <listitem> - <para>If you are using MS-DOS then download <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/fdimage.exe">fdimage.exe</ulink> - or get it from <filename>tools\fdimage.exe</filename> on the CDROM - and then run it like so:</para> - - <screen><prompt>E:\></prompt> <userinput>tools\fdimage floppies\kern.flp a:</userinput></screen> - - <para>The <emphasis>fdimage</emphasis> program will format the - <devicename>A:</devicename> drive and then copy the - <filename>kern.flp</filename> image onto it (assuming that you are - at the top level of a FreeBSD distribution and the floppy images - live in the <filename>floppies</filename> subdirectory, as is - typically the case).</para> - </listitem> - - <listitem> - <para>If you are using a UNIX system to create the floppy - images:</para> - - <screen>&prompt.root; <userinput>dd if=kern.flp of=<replaceable>disk_device</replaceable></userinput></screen> - - <para><replaceable>disk_device</replaceable> is the - <filename>/dev</filename> entry for the floppy drive. On FreeBSD - systems, this is <filename>/dev/rfd0</filename> for the - <devicename>A:</devicename> drive and - <filename>/dev/rfd1</filename> for the <devicename>B:</devicename> - drive.</para> - </listitem> - </itemizedlist> - </step> - - <step> - <para>With the <filename>kern.flp</filename> in the - <devicename>A:</devicename> drive, reboot your computer. The next - request you should get is for the <filename>mfsroot.flp</filename> - floppy, after which the installation will proceed normally.</para> - - <para>If you do <emphasis>not</emphasis> type anything at the boot - prompt which appears during this process, 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.</para> - </step> - - <step> - <para>When the booting process is finished, The main FreeBSD - installation menu will be displayed.</para> - </step> - </procedure> - - <para><emphasis>If something goes wrong…</emphasis></para> - - <para>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 <link linkend="install-hw">supported - configurations</link> section of this installation guide to be sure that - your hardware is indeed supported by FreeBSD.</para> - - <para>If your hardware is supported, reset the computer and when the visual - kernel configuration choice is presented, take it. 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 configuration editor to - tell FreeBSD where things are.</para> - - <para>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.</para> - - <warning> - <para>Do not disable any device you will need during installation, such as - your screen (<devicename>sc0</devicename>). If the installation wedges - or fails mysteriously after leaving the configuration editor, you have - probably removed or changed something that you should not have. Simply - reboot and try again.</para> - </warning> - - <para>In the configuration mode, you can:</para> - - <itemizedlist> - <listitem> - <para>List the device drivers installed in the kernel.</para> - </listitem> - - <listitem> - <para>Disable device drivers for hardware not present in your - system.</para> - </listitem> - - <listitem> - <para>Change the IRQ, DRQ, and IO port addresses used by a device - driver.</para> - </listitem> - </itemizedlist> - - <para>After adjusting the kernel to match how you have your hardware - configured, type <command>Q</command> to continue booting with the new - settings.</para> - - <para>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 <link - linkend="kernelconfig" >Kernel configuration</link> for more information - on creating custom kernels.</para> - - <sect1 id="install-hw"> - <title>Supported Configurations</title> - - <para>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.</para> - - <para>A minimum of four megabytes of RAM is required to run FreeBSD. To - run the X Window System, eight megabytes of RAM is the recommended - minimum.</para> - - <para>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.</para> - - <sect2> - <title>Disk Controllers</title> - - <itemizedlist> - <listitem> - <para>WD1003 (any generic MFM/RLL)</para> - </listitem> - - <listitem> - <para>WD1007 (any generic IDE/ESDI)</para> - </listitem> - - <listitem> - <para>IDE</para> - </listitem> - - <listitem> - <para>ATA</para> - </listitem> - - <listitem> - <para>Adaptec 1535 ISA SCSI controllers</para> - </listitem> - - <listitem> - <para>Adaptec 154x series ISA SCSI controllers</para> - </listitem> - - <listitem> - <para>Adaptec 174x series EISA SCSI controller in standard and - enhanced mode.</para> - </listitem> - - <listitem> - <para>Adaptec 274X/284X/2920C/2930U2/294x/2950/3940/3950 - (Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllers.</para> - </listitem> - - <listitem> - <para>Adaptec AIC7850, AIC7860, AIC7880, AIC789x, on-board SCSI - controllers.</para> - </listitem> - - <listitem> - <para>AdvanSys SCSI controllers (all models).</para> - </listitem> - - <listitem> - <para>BusLogic MultiMaster controllers:</para> - - <note> - <para>BusLogic/Mylex "Flashpoint" adapters are NOT yet - supported.</para> - </note> - - <itemizedlist> - <listitem> - <para>BusLogic MultiMaster "W" Series Host Adapters:</para> - - <itemizedlist> - <listitem> - <para>BT-948</para> - </listitem> - - <listitem> - <para>BT-958</para> - </listitem> - - <listitem> - <para>BT-958D</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>BusLogic MultiMaster "C" Series Host Adapters:</para> - - <itemizedlist> - <listitem> - <para>BT-946C</para> - </listitem> - - <listitem> - <para>BT-956C</para> - </listitem> - - <listitem> - <para>BT-956CD</para> - </listitem> - - <listitem> - <para>BT-445C</para> - </listitem> - - <listitem> - <para>BT-747C</para> - </listitem> - - <listitem> - <para>BT-757C</para> - </listitem> - - <listitem> - <para>BT-757CD</para> - </listitem> - - <listitem> - <para>BT-545C</para> - </listitem> - - <listitem> - <para>BT-540CF</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>BusLogic MultiMaster "S" Series Host Adapters:</para> - - <itemizedlist> - <listitem> - <para>BT-445S</para> - </listitem> - - <listitem> - <para>BT-747S</para> - </listitem> - - <listitem> - <para>BT-747D</para> - </listitem> - - <listitem> - <para>BT-757S</para> - </listitem> - - <listitem> - <para>BT-757D</para> - </listitem> - - <listitem> - <para>BT-545S</para> - </listitem> - - <listitem> - <para>BT-542D</para> - </listitem> - - <listitem> - <para>BT-742A</para> - </listitem> - - <listitem> - <para>BT-542B</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>BusLogic MultiMaster "A" Series Host Adapters:</para> - - <itemizedlist> - <listitem> - <para>BT-742A</para> - </listitem> - - <listitem> - <para>BT-542B</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>AMI FastDisk controllers that are true BusLogic - MultiMaster clones are also supported.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>DPT SmartCACHE Plus, SmartCACHE III, SmartRAID III, SmartCACHE - IV and SmartRAID IV SCSI/RAID controllers are supported. The DPT - SmartRAID/CACHE V is not yet supported.</para> - </listitem> - - <listitem> - <para>Compaq Intelligent Disk Array Controllers: IDA, IDA-2, IAES, - SMART, SMART-2/E, Smart-2/P, SMART-2SL, Smart Array 3200, - Smart Array 3100ES and Smart Array 221.</para> - </listitem> - - <listitem> - <para>SymBios (formerly NCR) 53C810, 53C810a, 53C815, 53C820, - 53C825a, 53C860, 53C875, 53C875j, 53C885, 53C895 and 53C896 PCI - SCSI controllers:</para> - - <itemizedlist> - <listitem> - <para>ASUS SC-200</para> - </listitem> - - <listitem> - <para>Data Technology DTC3130 (all variants)</para> - </listitem> - - <listitem> - <para>Diamond FirePort (all)</para> - </listitem> - - <listitem> - <para>NCR cards (all)</para> - </listitem> - - <listitem> - <para>Symbios cards (all)</para> - </listitem> - - <listitem> - <para>Tekram DC390W, 390U and 390F</para> - </listitem> - - <listitem> - <para>Tyan S1365</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>QLogic 1020, 1040, 1040B, 1080, 1240 and 2100 SCSI and Fibre - Channel Adapters</para> - </listitem> - - <listitem> - <para>DTC 3290 EISA SCSI controller in 1542 emulation mode.</para> - </listitem> - </itemizedlist> - - <para>With all supported SCSI controllers, full support is provided for - SCSI-I & SCSI-II peripherals, including hard disks, optical disks, - tape drives (including DAT and 8mm Exabyte), medium changers, - processor target devices and CDROM drives. WORM devices that support - CDROM commands are supported for read-only access by the CDROM driver. - WORM/CD-R/CD-RW writing support is provided by cdrecord, which is in - the ports tree.</para> - - <para>The following CD-ROM type systems are supported at this - time:</para> - - <itemizedlist> - <listitem> - <para>SoundBlaster SCSI and ProAudio Spectrum SCSI - (<literal>cd</literal>)</para> - </listitem> - - <listitem> - <para>Mitsumi (all models) proprietary interface - (<literal>mcd</literal>)</para> - </listitem> - - <listitem> - <para>Matsushita/Panasonic (Creative) CR-562/CR-563 proprietary - interface (<literal>matcd</literal>)</para> - </listitem> - - <listitem> - <para>Sony proprietary interface (<literal>scd</literal>)</para> - </listitem> - - <listitem> - <para>ATAPI IDE interface (<literal>wcd</literal>)</para> - </listitem> - </itemizedlist> - - <para>The following drivers were supported under the old SCSI subsystem, - but are NOT YET supported under the new CAM SCSI subsystem:</para> - - <itemizedlist> - <listitem> - <para>Tekram DC390 and DC390T controllers (maybe other cards based - on the AMD 53c974 as well).</para> - </listitem> - - <listitem> - <para>NCR5380/NCR53400 ("ProAudio Spectrum") SCSI controller.</para> - </listitem> - - <listitem> - <para>UltraStor 14F, 24F and 34F SCSI controllers.</para> - </listitem> - - <listitem> - <para>Seagate ST01/02 SCSI controllers.</para> - </listitem> - - <listitem> - <para>Future Domain 8xx/950 series SCSI controllers.</para> - </listitem> - - <listitem> - <para>WD7000 SCSI controller.</para> - </listitem> - - <listitem> - <para>Adaptec 1510 series ISA SCSI controllers (not for bootable - devices)</para> - </listitem> - - <listitem> - <para>Adaptec 152x series ISA SCSI controllers</para> - </listitem> - - <listitem> - <para>Adaptec AIC-6260 and AIC-6360 based boards, which includes the - AHA-152x and SoundBlaster SCSI cards.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="install-nics"> - <title>Ethernet cards</title> - - <itemizedlist> - <listitem> - <para>Allied-Telesis AT1700 and RE2000 cards</para> - </listitem> - - <listitem> - <para>SMC Elite 16 WD8013 Ethernet interface, and most other - WD8003E, WD8003EBT, WD8003W, WD8013W, WD8003S, WD8003SBT and - WD8013EBT based clones. SMC Elite Ultra and 9432TX based cards - are also supported.</para> - </listitem> - - <listitem> - <para>DEC EtherWORKS III NICs (DE203, DE204, and DE205)</para> - </listitem> - - <listitem> - <para>DEC EtherWORKS II NICs (DE200, DE201, DE202, and DE422)</para> - </listitem> - - <listitem> - <para>DEC DC21040/DC21041/DC21140 based NICs:</para> - - <itemizedlist> - <listitem> - <para>ASUS PCI-L101-TB</para> - </listitem> - - <listitem> - <para>Accton ENI1203</para> - </listitem> - - <listitem> - <para>Cogent EM960PCI</para> - </listitem> - - <listitem> - <para>Compex CPXPCI/32C</para> - </listitem> - - <listitem> - <para>D-Link DE-530</para> - </listitem> - - <listitem> - <para>DEC DE435</para> - </listitem> - - <listitem> - <para>DEC DE450</para> - </listitem> - - <listitem> - <para>Danpex EN-9400P3</para> - </listitem> - - <listitem> - <para>JCIS Condor JC1260</para> - </listitem> - - <listitem> - <para>Kingston KNE100TX</para> - </listitem> - - <listitem> - <para>Linksys EtherPCI</para> - </listitem> - - <listitem> - <para>Mylex LNP101</para> - </listitem> - - <listitem> - <para>SMC EtherPower 10/100 (Model 9332)</para> - </listitem> - - <listitem> - <para>SMC EtherPower (Model 8432)</para> - </listitem> - - <listitem> - <para>SMC EtherPower (2)</para> - </listitem> - - <listitem> - <para>Znyx ZX314</para> - </listitem> - - <listitem> - <para>Znyx ZX342</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>DEC FDDI (DEFPA/DEFEA) NICs</para> - </listitem> - - <listitem> - <para>Fujitsu FMV-181 and FMV-182</para> - </listitem> - - <listitem> - <para>Fujitsu MB86960A/MB86965A</para> - </listitem> - - <listitem> - <para>Intel EtherExpress</para> - </listitem> - - <listitem> - <para>Intel EtherExpress Pro/100B 100Mbit.</para> - </listitem> - - <listitem> - <para>Isolan AT 4141-0 (16 bit)</para> - </listitem> - - <listitem> - <para>Isolink 4110 (8 bit)</para> - </listitem> - - <listitem> - <para>Lucent WaveLAN wireless networking interface.</para> - </listitem> - - <listitem> - <para>Novell NE1000, NE2000, and NE2100 ethernet interface.</para> - </listitem> - - <listitem> - <para>3Com 3C501 cards</para> - </listitem> - - <listitem> - <para>3Com 3C503 Etherlink II</para> - </listitem> - - <listitem> - <para>3Com 3c505 Etherlink/+</para> - </listitem> - - <listitem> - <para>3Com 3C507 Etherlink 16/TP</para> - </listitem> - - <listitem> - <para>3Com 3C509, 3C579, 3C589 (PCMCIA) Etherlink III</para> - </listitem> - - <listitem> - <para>3Com 3C590, 3C595 Etherlink III</para> - </listitem> - - <listitem> - <para>3Com 3C90x cards.</para> - </listitem> - - <listitem> - <para>HP PC Lan Plus (27247B and 27252A)</para> - </listitem> - - <listitem> - <para>Toshiba ethernet cards</para> - </listitem> - - <listitem> - <para>PCMCIA ethernet cards from IBM and National Semiconductor are - also supported.</para> - </listitem> - </itemizedlist> - - <note> - <para>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.</para> - </note> - </sect2> - - <sect2 id="install-misc"> - <title>Miscellaneous devices</title> - - <itemizedlist> - <listitem> - <para>AST 4 port serial card using shared IRQ.</para> - </listitem> - - <listitem> - <para>ARNET 8 port serial card using shared IRQ.</para> - </listitem> - - <listitem> - <para>BOCA IOAT66 6 port serial card using shared IRQ.</para> - </listitem> - - <listitem> - <para>BOCA 2016 16 port serial card using shared IRQ.</para> - </listitem> - - <listitem> - <para>Cyclades Cyclom-y Serial Board.</para> - </listitem> - - <listitem> - <para>STB 4 port card using shared IRQ.</para> - </listitem> - - <listitem> - <para>SDL Communications Riscom/8 Serial Board.</para> - </listitem> - - <listitem> - <para>SDL Communications RISCom/N2 and N2pci sync serial - cards.</para> - </listitem> - - <listitem> - <para>Digiboard Sync/570i high-speed sync serial card.</para> - </listitem> - - <listitem> - <para>Decision-Computer Intl. “Eight-Serial” 8 port - serial cards using shared IRQ.</para> - </listitem> - - <listitem> - <para>Adlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum, - Gravis UltraSound, Gravis UltraSound MAX and Roland MPU-401 sound - cards.</para> - </listitem> - - <listitem> - <para>Matrox Meteor video frame grabber.</para> - </listitem> - - <listitem> - <para>Creative Labs Video spigot frame grabber.</para> - </listitem> - - <listitem> - <para>Omnimedia Talisman frame grabber.</para> - </listitem> - - <listitem> - <para>Brooktree BT848 chip based frame grabbers.</para> - </listitem> - - <listitem> - <para>X-10 power controllers.</para> - </listitem> - - <listitem> - <para>PC joystick and speaker.</para> - </listitem> - </itemizedlist> - - <para>FreeBSD does not currently support IBM's microchannel (MCA) - bus.</para> - </sect2> - </sect1> - - <sect1> - <title>Preparing for the Installation</title> - - <para>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.</para> - - <sect2> - <title>Before installing from CDROM</title> - - <para>If your CDROM is of an unsupported type, then please skip to <link - linkend="install-msdos">MS-DOS Preparation</link>.</para> - - <para>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 <command>install.bat</command> batch file or you can make - boot floppies with the <command>makeflp.bat</command> command.</para> - - <para>For the easiest interface of all (from DOS), type - <command>view</command>. This will bring up a DOS menu utility that - leads you through all the available options.</para> - - <para>If you are creating the boot floppies from a UNIX machine, see - <link linkend="install">the beginning of this guide</link> for - examples of how to create the boot floppies.</para> - - <para>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.</para> - - <para>After your system is fully installed and you have rebooted from - the hard disk, you can mount the CDROM at any time by typing: - <command>mount /cdrom</command></para> - - <para>Before removing the CD again, also note that it is necessary to - first type: <command>umount /cdrom</command>. Do not just remove it - from the drive!</para> - - <note> - <para>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).</para> - </note> - - <para>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):</para> - - <programlisting> -ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting> - - <para>Anyone with network connectivity to your machine (and permission - to log into it) can now chose a Media type of FTP and type in: - <userinput>ftp://<replaceable>your machine</replaceable></userinput> - after picking “Other” in the ftp sites menu.</para> - </sect2> - - <sect2> - <title>Before installing from Floppy</title> - - <para>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.</para> - - <para>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 - <emphasis>must</emphasis> be formatted using the MS-DOS FORMAT - command. If you are using Windows, use the Windows File Manager - format command.</para> - - <para>Do <emphasis>not</emphasis> 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!</para> - - <para>If you are creating the floppies from another FreeBSD machine, a - format is still not a bad idea though you do not need to put a DOS - filesystem on each floppy. You can use the - <command>disklabel</command> and <command>newfs</command> commands to - put a UFS filesystem on them instead, as the following sequence of - commands (for a 3.5" 1.44MB floppy disk) illustrates:</para> - - <screen>&prompt.root; <userinput>fdformat -f 1440 fd0.1440</userinput> -&prompt.root; <userinput>disklabel -w -r fd0.1440 floppy3</userinput> -&prompt.root; <userinput>newfs -t 2 -u 18 -l 1 -i 65536 /dev/rfd0</userinput></screen> - - <note> - <para>Use <literal>fd0.1200</literal> and <literal>floppy5</literal> - for 5.25" 1.2MB disks.</para> - </note> - - <para>Then you can mount and write to them like any other file - system.</para> - - <para>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.: <filename>a:\bin\bin.aa</filename>, - <filename>a:\bin\bin.ab</filename>, and so on.</para> - - <para>Once you come to the Media screen of the install, select - “Floppy” and you will be prompted for the rest.</para> - </sect2> - - <sect2 id="install-msdos"> - <title>Before installing from a MS-DOS partition</title> - - <para>To prepare for installation from an MS-DOS partition, copy the - files from the distribution into a directory called - <filename>c:\freebsd</filename>. The directory tree structure of the - CDROM must be partially reproduced within this directory so we suggest - using the DOS <command>xcopy</command> command. For example, to - prepare for a minimal installation of FreeBSD:</para> - - <screen><prompt>C:\></prompt> <userinput>md c:\freebsd</userinput> -<prompt>C:\></prompt> <userinput>xcopy /s e:\bin c:\freebsd\bin\</userinput> -<prompt>C:\></prompt> <userinput>xcopy /s e:\manpages c:\freebsd\manpages\</userinput></screen> - - <para>Assuming that <devicename>C:</devicename> is where you have free - space and <devicename>E:</devicename> is where your CDROM is - mounted.</para> - - <para>For as many <abbrev>DISTS</abbrev> you wish to install from MS-DOS - (and you have free space for), install each one under - <filename>c:\freebsd</filename> — the <literal>BIN</literal> dist - is only the minimal requirement.</para> - </sect2> - - <sect2> - <title>Before installing from QIC/SCSI Tape</title> - - <para>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:</para> - - <screen>&prompt.root; <userinput>cd /freebsd/distdir</userinput> -&prompt.root; <userinput>tar cvf /dev/rwt0 dist1 ... dist2</userinput></screen> - - <para>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 <emphasis>full</emphasis> - 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.</para> - - <note> - <para>When going to do the installation, the tape must be in the drive - <emphasis>before</emphasis> booting from the boot floppy. The - installation probe may otherwise fail to find it.</para> - </note> - </sect2> - - <sect2> - <title>Before installing over a network</title> - - <para>You can do network installations over 3 types of communications - links:</para> - - <variablelist> - <varlistentry> - <term>Serial port</term> - - <listitem> - <para>SLIP or PPP</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Parallel port</term> - - <listitem> - <para>PLIP (laplink cable)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Ethernet</term> - - <listitem> - <para>A standard ethernet controller (includes some - PCMCIA).</para> - </listitem> - </varlistentry> - </variablelist> - - <para>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.</para> - - <para>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 how to dial your ISP using the - “AT commands” specific to your modem, as the PPP dialer - provides only a very simple terminal emulator. If you are using PAP or - CHAP, you will need to type the necessary <command>set - authname</command> and <command>set authkey</command> commands - before typing <command>term</command>. Refer to the user-ppp <link - linkend="userppp">handbook</link> and <ulink - URL="../FAQ/userppp.html">FAQ</ulink> entries for further - information. If you have problems, logging can be directed to the - screen using the command <command>set log local ...</command>.</para> - - <para>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.</para> - - <para>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 <link linkend="install-hw" >Supported - Hardware</link>. If you are using one of the supported PCMCIA - ethernet cards, also be sure that it is plugged in - <emphasis>before</emphasis> the laptop is powered on! FreeBSD does - not, unfortunately, currently support hot insertion of PCMCIA cards - during installation.</para> - - <para>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 <emphasis>first</emphasis> - before trying this type of installation.</para> - - <para>Once you have a network link of some sort working, the - installation can continue over NFS or FTP.</para> - - <sect3> - <title>Preparing for NFS installation</title> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - - <para>In order for NFS installation to work, the server must support - subdir mounts, e.g., if your FreeBSD &rel.current; distribution - directory lives on: - <filename>ziggy:/usr/archive/stuff/FreeBSD</filename> Then - <hostid>ziggy</hostid> will have to allow the direct mounting of - <filename>/usr/archive/stuff/FreeBSD</filename>, not just - <filename>/usr</filename> or - <filename>/usr/archive/stuff</filename>.</para> - - <para>In FreeBSD's <filename>/etc/exports</filename> file, this is - controlled by the <option>-alldirs</option> option. Other NFS - servers may have different conventions. If you are getting - <errortype>Permission Denied</errortype> messages from the server - then it is likely that you do not have this enabled properly.</para> - </sect3> - - <sect3> - <title>Preparing for FTP Installation</title> - - <para>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.</para> - - <para>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:</para> - - <screen><userinput>ftp://165.113.121.81/pub/FreeBSD/&rel.current;-RELEASE</userinput></screen> - - <para>There are two FTP installation modes you can use:</para> - - <variablelist> - <varlistentry> - <term>FTP Active</term> - - <listitem> - <para>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!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FTP Passive</term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - </variablelist> - - <note> - <para>Active and passive modes are not the same as a - “proxy” connection, where a proxy FTP server is - listening and forwarding FTP requests!</para> - </note> - - <para>For a proxy FTP server, you should usually give name of the - server you really want as a part of the username, after an @-sign. - The proxy server then 'fakes' the real server. An example: Say you - want to install from <hostid role="fqdn">ftp.FreeBSD.org</hostid>, - using the proxy FTP server <hostid role="fqdn">foo.bar.com</hostid>, - listening on port 1234.</para> - - <para>In this case, you go to the options menu, set the FTP username - to ftp@ftp.FreeBSD.org, and the password to your e-mail address. As - your installation media, you specify FTP (or passive FTP, if the - proxy support it), and the URL - <literal>ftp://foo.bar.com:1234/pub/FreeBSD </literal></para> - - <para><filename>/pub/FreeBSD</filename> from <hostid - role="fqdn">ftp.FreeBSD.org</hostid> is proxied under <hostid - role="fqdn">foo.bar.com</hostid>, allowing you to install from - <emphasis>that</emphasis> machine (which fetch the files from - <hostid role="fqdn">ftp.FreeBSD.org</hostid> as your installation - requests them).</para> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>Installing FreeBSD</title> - - <para>Once you have taken note of the appropriate preinstallation steps, - you should be able to install FreeBSD without any further - trouble.</para> - - <para>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.</para> - - <para>The FreeBSD boot floppies contain 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!</para> - - <para>Meanwhile, you may also find the following “typical - installation sequence” to be helpful:</para> - - <orderedlist> - <listitem> - <para>Boot the <filename>kern.flp</filename> floppy and, when asked, - remove it and insert the <filename>mfsroot.flp</filename> floppy and - hit return. After a boot sequence which can take anywhere from 30 - seconds to 3 minutes, depending on your hardware, you should be - presented with a menu of initial choices. If the - <filename>kern.flp</filename> 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.</para> - </listitem> - - <listitem> - <para>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 <emphasis>please</emphasis> read this - thoroughly!</para> - </listitem> - - <listitem> - <para>Select the Options item and set any special preferences you may - have.</para> - </listitem> - - <listitem> - <para>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 have never used - FreeBSD before then the Novice installation method is most - recommended.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>MS-DOS User's Questions and Answers</title> - - <para>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.</para> - - <para><emphasis>Help! I have no space! Do I need to delete everything - first?</emphasis></para> - - <para>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 <filename>tools</filename> - directory on the FreeBSD CDROM or on the various FreeBSD ftp sites, to - be quite useful.</para> - - <para>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 <emphasis>Distributions</emphasis> menu for an estimation of how - much free space you will need for the kind of installation you - want.</para> - - <para><emphasis>Can I use compressed MS-DOS filesystems from - FreeBSD?</emphasis></para> - - <para>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!). <emphasis>Do - not remove that file!</emphasis> You will probably regret it - greatly!</para> - - <para>It is probably better to create another uncompressed MS-DOS primary - partition and use this for communications between MS-DOS and - FreeBSD.</para> - - <para><emphasis>Can I mount my MS-DOS extended - partitions?</emphasis></para> - - <para>Yes. DOS extended partitions are mapped in at the end of the other - “slices” in FreeBSD, e.g. your <devicename>D:</devicename> - drive might be <filename>/dev/da0s5</filename>, your - <devicename>E:</devicename> drive <filename>/dev/da0s6</filename>, and - so on. This example assumes, of course, that your extended partition is - on SCSI drive 0. For IDE drives, substitute <filename>wd</filename> for - <filename>da</filename> appropriately. You otherwise mount extended - partitions exactly like you would mount any other DOS drive, - e.g.:</para> - - <screen>&prompt.root; <userinput>mount -t msdos /dev/da0s5 /dos_d</userinput></screen> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/internals/chapter.sgml b/en/handbook/internals/chapter.sgml deleted file mode 100644 index dad41115ae..0000000000 --- a/en/handbook/internals/chapter.sgml +++ /dev/null @@ -1,1864 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.11 1999-08-05 20:48:13 nik Exp $ ---> - -<chapter id="internals"> - <title>FreeBSD Internals</title> - - <sect1 id="booting"> - <title>The FreeBSD Booting Process</title> - - <para><emphasis>Contributed by &a.phk;. v1.1, April - 26th.</emphasis></para> - - <para>Booting FreeBSD is essentially a three step process: load the - kernel, determine the root filesystem and initialize user-land things. - This leads to some interesting possibilities shown below.</para> - - <sect2> - <title>Loading a kernel</title> - - <para>We presently have three basic mechanisms for loading the kernel as - described below: they all pass some information to the kernel to help - the kernel decide what to do next.</para> - - <variablelist> - <varlistentry> - <term>Biosboot</term> - - <listitem> - <para>Biosboot is our “bootblocks”. It consists of - two files which will be installed in the first 8Kbytes of the - floppy or hard-disk slice to be booted from.</para> - - <para>Biosboot can load a kernel from a FreeBSD filesystem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Dosboot</term> - - <listitem> - <para>Dosboot was written by DI. Christian Gusenbauer, and is - unfortunately at this time one of the few pieces of code that - will not compile under FreeBSD itself because it is written for - Microsoft compilers.</para> - - <para>Dosboot will boot the kernel from a MS-DOS file or from a - FreeBSD filesystem partition on the disk. It attempts to - negotiate with the various and strange kinds of memory manglers - that lurk in high memory on MS/DOS systems and usually wins them - for its case.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Netboot</term> - - <listitem> - <para>Netboot will try to find a supported Ethernet card, and use - BOOTP, TFTP and NFS to find a kernel file to boot.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Determine the root filesystem</title> - - <para>Once the kernel is loaded and the boot-code jumps to it, the - kernel will initialize itself, trying to determine what hardware is - present and so on; it then needs to find a root filesystem.</para> - - <para>Presently we support the following types of root - filesystems:</para> - - <variablelist> - <varlistentry> - <term>UFS</term> - - <listitem> - <para>This is the most normal type of root filesystem. It can - reside on a floppy or on hard disk.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>MSDOS</term> - - <listitem> - <para>While this is technically possible, it is not particular - useful because of the <acronym>FAT</acronym> filesystem's - inability to deal with links, device nodes and other such - “UNIXisms”.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>MFS</term> - - <listitem> - <para>This is actually a UFS filesystem which has been compiled - into the kernel. That means that the kernel does not really - need any hard disks, floppies or other hardware to - function.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>CD9660</term> - - <listitem> - <para>This is for using a CD-ROM as root filesystem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NFS</term> - - <listitem> - <para>This is for using a fileserver as root filesystem, basically - making it a diskless machine.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Initialize user-land things</title> - - <para>To get the user-land going, the kernel, when it has finished - initialization, will create a process with <literal>pid == 1</literal> - and execute a program on the root filesystem; this program is normally - <filename>/sbin/init</filename>.</para> - - <para>You can substitute any program for <command>/sbin/init</command>, - as long as you keep in mind that:</para> - - <para>there is no stdin/out/err unless you open it yourself. If you - exit, the machine panics. Signal handling is special for <literal>pid - == 1</literal>.</para> - - <para>An example of this is the <command>/stand/sysinstall</command> - program on the installation floppy.</para> - </sect2> - - <sect2> - <title>Interesting combinations</title> - - <para>Boot a kernel with a MFS in it with a special - <filename>/sbin/init</filename> which...</para> - - <variablelist> - <varlistentry> - <term>A — Using DOS</term> - - <listitem> - <itemizedlist> - <listitem> - <para>mounts your <filename>C:</filename> as - <filename>/C:</filename></para> - </listitem> - - <listitem> - <para>Attaches <filename>C:/freebsd.fs</filename> on - <filename>/dev/vn0</filename></para> - </listitem> - - <listitem> - <para>mounts <filename>/dev/vn0</filename> as - <filename>/rootfs</filename></para> - </listitem> - - <listitem> - <para>makes symlinks - <filename>/rootfs/bin</filename> -> - <filename>/bin</filename> - <filename>/rootfs/etc</filename> -> - <filename>/etc</filename> - <filename>/rootfs/sbin</filename> -> - <filename>/sbin</filename> (etc...)</para> - </listitem> - </itemizedlist> - - <para>Now you are running FreeBSD without repartitioning your hard - disk...</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>B — Using NFS</term> - - <listitem> - <para>NFS mounts your <filename>server:~you/FreeBSD</filename> as - <filename>/nfs</filename>, chroots to <filename>/nfs</filename> - and executes <filename>/sbin/init</filename> there</para> - - <para>Now you are running FreeBSD diskless, even though you do not - control the NFS server...</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>C — Start an X-server</term> - - <listitem> - <para>Now you have an X-terminal, which is better than that dingy - X-under-windows-so-slow-you-can-see-what-it-does thing that your - boss insist is better than forking out money on hardware.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>D — Using a tape</term> - - <listitem> - <para>Takes a copy of <filename>/dev/rwd0</filename> and writes it - to a remote tape station or fileserver.</para> - - <para>Now you finally get that backup you should have made a year - ago...</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>E — Acts as a firewall/web-server/what do I - know...</term> - - <listitem> - <para>This is particularly interesting since you can boot from a - write- protected floppy, but still write to your root - filesystem...</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="memoryuse"> - <title>PC Memory Utilization</title> - - <para><emphasis>Contributed by &a.joerg;. 16 Apr - 1995.</emphasis></para> - - <para><emphasis>A short description of how FreeBSD uses memory on the i386 - platform</emphasis></para> - - <para>The boot sector will be loaded at <literal>0:0x7c00</literal>, and - relocates itself immediately to <literal>0x7c0:0</literal>. (This is - nothing magic, just an adjustment for the <literal>%cs</literal> - selector, done by an <literal>ljmp</literal>.)</para> - - <para>It then loads the first 15 sectors at <literal>0x10000</literal> - (segment <makevar>BOOTSEG</makevar> in the biosboot Makefile), and sets - up the stack to work below <literal>0x1fff0</literal>. After this, it - jumps to the entry of boot2 within that code. I.e., it jumps over - itself and the (dummy) partition table, and it is going to adjust the - %cs selector—we are still in 16-bit mode there.</para> - - <para>boot2 asks for the boot file, and examines the - <filename>a.out</filename> header. It masks the file entry point - (usually <literal>0xf0100000</literal>) by - <literal>0x00ffffff</literal>, and loads the file there. Hence the - usual load point is 1 MB (<literal>0x00100000</literal>). During load, - the boot code toggles back and forth between real and protected mode, to - use the BIOS in real mode.</para> - - <para>The boot code itself uses segment selectors <literal>0x18</literal> - and <literal>0x20</literal> for <literal>%cs</literal> and - <literal>%ds/%es</literal> in protected mode, and - <literal>0x28</literal> to jump back into real mode. The kernel is - finally started with <literal>%cs</literal> <literal>0x08</literal> and - <literal>%ds/%es/%ss</literal> <literal>0x10</literal>, which refer to - dummy descriptors covering the entire address space.</para> - - <para>The kernel will be started at its load point. Since it has been - linked for another (high) address, it will have to execute PIC until the - page table and page directory stuff is setup properly, at which point - paging will be enabled and the kernel will finally run at the address - for which it was linked.</para> - - <para><emphasis>Contributed by &a.dg;. 16 Apr - 1995.</emphasis></para> - - <para>The physical pages immediately following the kernel BSS contain - proc0's page directory, page tables, and upages. Some time later when - the VM system is initialized, the physical memory between - <literal>0x1000-0x9ffff</literal> and the physical memory after the - kernel (text+data+bss+proc0 stuff+other misc) is made available in the - form of general VM pages and added to the global free page list.</para> - </sect1> - - <sect1 id="dma"> - <title>DMA: What it Is and How it Works</title> - - <para><emphasis>Copyright © 1995,1997 &a.uhclem;, All Rights - Reserved. 10 December 1996. Last Update 8 October - 1997.</emphasis></para> - - <para>Direct Memory Access (DMA) is a method of allowing data to be moved - from one location to another in a computer without intervention from the - central processor (CPU).</para> - - <para>The way that the DMA function is implemented varies between computer - architectures, so this discussion will limit itself to the - implementation and workings of the DMA subsystem on the IBM Personal - Computer (PC), the IBM PC/AT and all of its successors and - clones.</para> - - <para>The PC DMA subsystem is based on the Intel 8237 DMA controller. The - 8237 contains four DMA channels that can be programmed independently and - any one of the channels may be active at any moment. These channels are - numbered 0, 1, 2 and 3. Starting with the PC/AT, IBM added a second - 8237 chip, and numbered those channels 4, 5, 6 and 7.</para> - - <para>The original DMA controller (0, 1, 2 and 3) moves one byte in each - transfer. The second DMA controller (4, 5, 6, and 7) moves 16-bits from - two adjacent memory locations in each transfer, with the first byte - always coming from an even-numbered address. The two controllers are - identical components and the difference in transfer size is caused by - the way the second controller is wired into the system.</para> - - <para>The 8237 has two electrical signals for each channel, named DRQ and - -DACK. There are additional signals with the names HRQ (Hold Request), - HLDA (Hold Acknowledge), -EOP (End of Process), and the bus control - signals -MEMR (Memory Read), -MEMW (Memory Write), -IOR (I/O Read), and - -IOW (I/O Write).</para> - - <para>The 8237 DMA is known as a “fly-by” DMA controller. - This means that the data being moved from one location to another does - not pass through the DMA chip and is not stored in the DMA chip. - Subsequently, the DMA can only transfer data between an I/O port and a - memory address, but not between two I/O ports or two memory - locations.</para> - - <note> - <para>The 8237 does allow two channels to be connected together to allow - memory-to-memory DMA operations in a non-“fly-by” mode, - but nobody in the PC industry uses this scarce resource this way since - it is faster to move data between memory locations using the - CPU.</para> - </note> - - <para>In the PC architecture, each DMA channel is normally activated only - when the hardware that uses a given DMA channel requests a transfer by - asserting the DRQ line for that channel.</para> - - <sect2> - <title>A Sample DMA transfer</title> - - <para>Here is an example of the steps that occur to cause and perform a - DMA transfer. In this example, the floppy disk controller (FDC) has - just read a byte from a diskette and wants the DMA to place it in - memory at location 0x00123456. The process begins by the FDC - asserting the DRQ2 signal (the DRQ line for DMA channel 2) to alert - the DMA controller.</para> - - <para>The DMA controller will note that the DRQ2 signal is asserted. The - DMA controller will then make sure that DMA channel 2 has been - programmed and is unmasked (enabled). The DMA controller also makes - sure that none of the other DMA channels are active or want to be - active and have a higher priority. Once these checks are complete, - the DMA asks the CPU to release the bus so that the DMA may use the - bus. The DMA requests the bus by asserting the HRQ signal which goes - to the CPU.</para> - - <para>The CPU detects the HRQ signal, and will complete executing the - current instruction. Once the processor has reached a state where it - can release the bus, it will. Now all of the signals normally - generated by the CPU (-MEMR, -MEMW, -IOR, -IOW and a few others) are - placed in a tri-stated condition (neither high or low) and then the - CPU asserts the HLDA signal which tells the DMA controller that it is - now in charge of the bus.</para> - - <para>Depending on the processor, the CPU may be able to execute a few - additional instructions now that it no longer has the bus, but the CPU - will eventually have to wait when it reaches an instruction that must - read something from memory that is not in the internal processor cache - or pipeline.</para> - - <para>Now that the DMA “is in charge”, the DMA activates its - -MEMR, -MEMW, -IOR, -IOW output signals, and the address outputs from - the DMA are set to 0x3456, which will be used to direct the byte that - is about to transferred to a specific memory location.</para> - - <para>The DMA will then let the device that requested the DMA transfer - know that the transfer is commencing. This is done by asserting the - -DACK signal, or in the case of the floppy disk controller, -DACK2 is - asserted.</para> - - <para>The floppy disk controller is now responsible for placing the byte - to be transferred on the bus Data lines. Unless the floppy controller - needs more time to get the data byte on the bus (and if the peripheral - does need more time it alerts the DMA via the READY signal), the DMA - will wait one DMA clock, and then de-assert the -MEMW and -IOR signals - so that the memory will latch and store the byte that was on the bus, - and the FDC will know that the byte has been transferred.</para> - - <para>Since the DMA cycle only transfers a single byte at a time, the - FDC now drops the DRQ2 signal, so the DMA knows that it is no longer - needed. The DMA will de-assert the -DACK2 signal, so that the FDC - knows it must stop placing data on the bus.</para> - - <para>The DMA will now check to see if any of the other DMA channels - have any work to do. If none of the channels have their DRQ lines - asserted, the DMA controller has completed its work and will now - tri-state the -MEMR, -MEMW, -IOR, -IOW and address signals.</para> - - <para>Finally, the DMA will de-assert the HRQ signal. The CPU sees - this, and de-asserts the HOLDA signal. Now the CPU activates its - -MEMR, -MEMW, -IOR, -IOW and address lines, and it resumes executing - instructions and accessing main memory and the peripherals.</para> - - <para>For a typical floppy disk sector, the above process is repeated - 512 times, once for each byte. Each time a byte is transferred, the - address register in the DMA is incremented and the counter in the DMA - that shows how many bytes are to be transferred is decremented.</para> - - <para>When the counter reaches zero, the DMA asserts the EOP signal, - which indicates that the counter has reached zero and no more data - will be transferred until the DMA controller is reprogrammed by the - CPU. This event is also called the Terminal Count (TC). There is only - one EOP signal, and since only DMA channel can be active at any - instant, the DMA channel that is currently active must be the DMA - channel that just completed its task.</para> - - <para>If a peripheral wants to generate an interrupt when the transfer - of a buffer is complete, it can test for its -DACKn signal and the EOP - signal both being asserted at the same time. When that happens, it - means the DMA will not transfer any more information for that - peripheral without intervention by the CPU. The peripheral can then - assert one of the interrupt signals to get the processors' attention. - In the PC architecture, the DMA chip itself is not capable of - generating an interrupt. The peripheral and its associated hardware - is responsible for generating any interrupt that occurs. - Subsequently, it is possible to have a peripheral that uses DMA but - does not use interrupts.</para> - - <para>It is important to understand that although the CPU always - releases the bus to the DMA when the DMA makes the request, this - action is invisible to both applications and the operating systems, - except for slight changes in the amount of time the processor takes to - execute instructions when the DMA is active. Subsequently, the - processor must poll the peripheral, poll the registers in the DMA - chip, or receive an interrupt from the peripheral to know for certain - when a DMA transfer has completed.</para> - </sect2> - - <sect2> - <title>DMA Page Registers and 16Meg address space limitations</title> - - <para>You may have noticed earlier that instead of the DMA setting the - address lines to 0x00123456 as we said earlier, the DMA only set - 0x3456. The reason for this takes a bit of explaining.</para> - - <para>When the original IBM PC was designed, IBM elected to use both DMA - and interrupt controller chips that were designed for use with the - 8085, an 8-bit processor with an address space of 16 bits (64K). - Since the IBM PC supported more than 64K of memory, something had to - be done to allow the DMA to read or write memory locations above the - 64K mark. What IBM did to solve this problem was to add an external - data latch for each DMA channel that holds the upper bits of the - address to be read to or written from. Whenever a DMA channel is - active, the contents of that latch are written to the address bus and - kept there until the DMA operation for the channel ends. IBM called - these latches “Page Registers”.</para> - - <para>So for our example above, the DMA would put the 0x3456 part of the - address on the bus, and the Page Register for DMA channel 2 would put - 0x0012xxxx on the bus. Together, these two values form the complete - address in memory that is to be accessed.</para> - - <para>Because the Page Register latch is independent of the DMA chip, - the area of memory to be read or written must not span a 64K physical - boundary. For example, if the DMA accesses memory location 0xffff, - after that transfer the DMA will then increment the address register - and the DMA will access the next byte at location 0x0000, not 0x10000. - The results of letting this happen are probably not intended.</para> - - <note> - <para>“Physical” 64K boundaries should not be confused - with 8086-mode 64K “Segments”, which are created by - mathematically adding a segment register with an offset register. - Page Registers have no address overlap and are mathematically OR-ed - together.</para> - </note> - - <para>To further complicate matters, the external DMA address latches on - the PC/AT hold only eight bits, so that gives us 8+16=24 bits, which - means that the DMA can only point at memory locations between 0 and - 16Meg. For newer computers that allow more than 16Meg of memory, the - standard PC-compatible DMA cannot access memory locations above - 16Meg.</para> - - <para>To get around this restriction, operating systems will reserve a - RAM buffer in an area below 16Meg that also does not span a physical - 64K boundary. Then the DMA will be programmed to transfer data from - the peripheral and into that buffer. Once the DMA has moved the data - into this buffer, the operating system will then copy the data from - the buffer to the address where the data is really supposed to be - stored.</para> - - <para>When writing data from an address above 16Meg to a DMA-based - peripheral, the data must be first copied from where it resides into a - buffer located below 16Meg, and then the DMA can copy the data from - the buffer to the hardware. In FreeBSD, these reserved buffers are - called “Bounce Buffers”. In the MS-DOS world, they are - sometimes called “Smart Buffers”.</para> - - <note> - <para>A new implementation of the 8237, called the 82374, allows 16 - bits of page register to be specified, allows access to the entire - 32 bit address space, without the use of bounce buffers.</para> - </note> - </sect2> - - <sect2> - <title>DMA Operational Modes and Settings</title> - - <para>The 8237 DMA can be operated in several modes. The main ones - are:</para> - - <variablelist> - <varlistentry> - <term>Single</term> - - <listitem> - <para>A single byte (or word) is transferred. The DMA must - release and re-acquire the bus for each additional byte. This is - commonly-used by devices that cannot transfer the entire block - of data immediately. The peripheral will request the DMA each - time it is ready for another transfer.</para> - - <para>The standard PC-compatible floppy disk controller (NEC 765) - only has a one-byte buffer, so it uses this mode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Block/Demand</term> - - <listitem> - <para>Once the DMA acquires the system bus, an entire block of - data is transferred, up to a maximum of 64K. If the peripheral - needs additional time, it can assert the READY signal to suspend - the transfer briefly. READY should not be used excessively, and - for slow peripheral transfers, the Single Transfer Mode should - be used instead.</para> - - <para>The difference between Block and Demand is that once a Block - transfer is started, it runs until the transfer count reaches - zero. DRQ only needs to be asserted until -DACK is asserted. - Demand Mode will transfer one more bytes until DRQ is - de-asserted, at which point the DMA suspends the transfer and - releases the bus back to the CPU. When DRQ is asserted later, - the transfer resumes where it was suspended.</para> - - <para>Older hard disk controllers used Demand Mode until CPU - speeds increased to the point that it was more efficient to - transfer the data using the CPU, particularly if the memory - locations used in the transfer were above the 16Meg mark.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Cascade</term> - - <listitem> - <para>This mechanism allows a DMA channel to request the bus, but - then the attached peripheral device is responsible for placing - the addressing information on the bus instead of the DMA. This - is also used to implement a technique known as “Bus - Mastering”.</para> - - <para>When a DMA channel in Cascade Mode receives control of the - bus, the DMA does not place addresses and I/O control signals on - the bus like the DMA normally does when it is active. Instead, - the DMA only asserts the -DACK signal for the active DMA - channel.</para> - - <para>At this point it is up to the peripheral connected to that - DMA channel to provide address and bus control signals. The - peripheral has complete control over the system bus, and can do - reads and/or writes to any address below 16Meg. When the - peripheral is finished with the bus, it de-asserts the DRQ line, - and the DMA controller can then return control to the CPU or to - some other DMA channel.</para> - - <para>Cascade Mode can be used to chain multiple DMA controllers - together, and this is exactly what DMA Channel 4 is used for in - the PC architecture. When a peripheral requests the bus on DMA - channels 0, 1, 2 or 3, the slave DMA controller asserts HLDREQ, - but this wire is actually connected to DRQ4 on the primary DMA - controller instead of to the CPU. The primary DMA controller, - thinking it has work to do on Channel 4, requests the bus from - the CPU using HLDREQ signal. Once the CPU grants the bus to the - primary DMA controller, -DACK4 is asserted, and that wire is - actually connected to the HLDA signal on the slave DMA - controller. The slave DMA controller then transfers data for - the DMA channel that requested it (0, 1, 2 or 3), or the slave - DMA may grant the bus to a peripheral that wants to perform its - own bus-mastering, such as a SCSI controller.</para> - - <para>Because of this wiring arrangement, only DMA channels 0, 1, - 2, 3, 5, 6 and 7 are usable with peripherals on PC/AT - systems.</para> - - <note> - <para>DMA channel 0 was reserved for refresh operations in early - IBM PC computers, but is generally available for use by - peripherals in modern systems.</para> - </note> - - <para>When a peripheral is performing Bus Mastering, it is - important that the peripheral transmit data to or from memory - constantly while it holds the system bus. If the peripheral - cannot do this, it must release the bus frequently so that the - system can perform refresh operations on main memory.</para> - - <para>The Dynamic RAM used in all PCs for main memory must be - accessed frequently to keep the bits stored in the components - “charged”. Dynamic RAM essentially consists of - millions of capacitors with each one holding one bit of data. - These capacitors are charged with power to represent a - <literal>1</literal> or drained to represent a - <literal>0</literal>. Because all capacitors leak, power must - be added at regular intervals to keep the <literal>1</literal> - values intact. The RAM chips actually handle the task of - pumping power back into all of the appropriate locations in RAM, - but they must be told when to do it by the rest of the computer - so that the refresh activity won't interfere with the computer - wanting to access RAM normally. If the computer is unable to - refresh memory, the contents of memory will become corrupted in - just a few milliseconds.</para> - - <para>Since memory read and write cycles “count” as - refresh cycles (a dynamic RAM refresh cycle is actually an - incomplete memory read cycle), as long as the peripheral - controller continues reading or writing data to sequential - memory locations, that action will refresh all of memory.</para> - - <para>Bus-mastering is found in some SCSI host interfaces and - other high-performance peripheral controllers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Autoinitialize</term> - - <listitem> - <para>This mode causes the DMA to perform Byte, Block or Demand - transfers, but when the DMA transfer counter reaches zero, the - counter and address are set back to where they were when the DMA - channel was originally programmed. This means that as long as - the peripheral requests transfers, they will be granted. It is - up to the CPU to move new data into the fixed buffer ahead of - where the DMA is about to transfer it when doing output - operations, and read new data out of the buffer behind where the - DMA is writing when doing input operations.</para> - - <para>This technique is frequently used on audio devices that have - small or no hardware “sample” buffers. There is - additional CPU overhead to manage this “circular” - buffer, but in some cases this may be the only way to eliminate - the latency that occurs when the DMA counter reaches zero and - the DMA stops transfers until it is reprogrammed.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Programming the DMA</title> - - <para>The DMA channel that is to be programmed should always be - “masked” before loading any settings. This is because the - hardware might unexpectedly assert the DRQ for that channel, and the - DMA might respond, even though not all of the parameters have been - loaded or updated.</para> - - <para>Once masked, the host must specify the direction of the transfer - (memory-to-I/O or I/O-to-memory), what mode of DMA operation is to be - used for the transfer (Single, Block, Demand, Cascade, etc), and - finally the address and length of the transfer are loaded. The length - that is loaded is one less than the amount you expect the DMA to - transfer. The LSB and MSB of the address and length are written to - the same 8-bit I/O port, so another port must be written to first to - guarantee that the DMA accepts the first byte as the LSB and the - second byte as the MSB of the length and address.</para> - - <para>Then, be sure to update the Page Register, which is external to - the DMA and is accessed through a different set of I/O ports.</para> - - <para>Once all the settings are ready, the DMA channel can be un-masked. - That DMA channel is now considered to be “armed”, and will - respond when the DRQ line for that channel is asserted.</para> - - <para>Refer to a hardware data book for precise programming details for - the 8237. You will also need to refer to the I/O port map for the PC - system, which describes where the DMA and Page Register ports are - located. A complete port map table is located below.</para> - </sect2> - - <sect2> - <title>DMA Port Map</title> - - <para>All systems based on the IBM-PC and PC/AT have the DMA hardware - located at the same I/O ports. The complete list is provided below. - Ports assigned to DMA Controller #2 are undefined on non-AT - designs.</para> - - <sect3> - <title>0x00–0x1f DMA Controller #1 (Channels 0, 1, 2 and - 3)</title> - - <para>DMA Address and Count Registers</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>0x00</entry> - <entry>write</entry> - <entry>Channel 0 starting address</entry> - </row> - - <row> - <entry>0x00</entry> - <entry>read</entry> - <entry>Channel 0 current address</entry> - </row> - - <row> - <entry>0x01</entry> - <entry>write</entry> - <entry>Channel 0 starting word count</entry> - </row> - - <row> - <entry>0x01</entry> - <entry>read</entry> - <entry>Channel 0 remaining word count</entry> - </row> - - <row> - <entry>0x02</entry> - <entry>write</entry> - <entry>Channel 1 starting address</entry> - </row> - - <row> - <entry>0x02</entry> - <entry>read</entry> - <entry>Channel 1 current address</entry> - </row> - - <row> - <entry>0x03</entry> - <entry>write</entry> - <entry>Channel 1 starting word count</entry> - </row> - - <row> - <entry>0x03</entry> - <entry>read</entry> - <entry>Channel 1 remaining word count</entry> - </row> - - <row> - <entry>0x04</entry> - <entry>write</entry> - <entry>Channel 2 starting address</entry> - </row> - - <row> - <entry>0x04</entry> - <entry>read</entry> - <entry>Channel 2 current address</entry> - </row> - - <row> - <entry>0x05</entry> - <entry>write</entry> - <entry>Channel 2 starting word count</entry> - </row> - - <row> - <entry>0x05</entry> - <entry>read</entry> - <entry>Channel 2 remaining word count</entry> - </row> - - <row> - <entry>0x06</entry> - <entry>write</entry> - <entry>Channel 3 starting address</entry> - </row> - - <row> - <entry>0x06</entry> - <entry>read</entry> - <entry>Channel 3 current address</entry> - </row> - - <row> - <entry>0x07</entry> - <entry>write</entry> - <entry>Channel 3 starting word count</entry> - </row> - - <row> - <entry>0x07</entry> - <entry>read</entry> - <entry>Channel 3 remaining word count</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>DMA Command Registers</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>0x08</entry> - <entry>write</entry> - <entry>Command Register</entry> - </row> - - <row> - <entry>0x08</entry> - <entry>read</entry> - <entry>Status Register</entry> - </row> - - <row> - <entry>0x09</entry> - <entry>write</entry> - <entry>Request Register</entry> - </row> - - <row> - <entry>0x09</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0x0a</entry> - <entry>write</entry> - <entry>Single Mask Register Bit</entry> - </row> - - <row> - <entry>0x0a</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0x0b</entry> - <entry>write</entry> - <entry>Mode Register</entry> - </row> - - <row> - <entry>0x0b</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0x0c</entry> - <entry>write</entry> - <entry>Clear LSB/MSB Flip-Flop</entry> - </row> - - <row> - <entry>0x0c</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0x0d</entry> - <entry>write</entry> - <entry>Master Clear/Reset</entry> - </row> - - <row> - <entry>0x0d</entry> - <entry>read</entry> - <entry>Temporary Register (not available on newer - versions)</entry> - </row> - <row> - <entry>0x0e</entry> - <entry>write</entry> - <entry>Clear Mask Register</entry> - </row> - - <row> - <entry>0x0e</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0x0f</entry> - <entry>write</entry> - <entry>Write All Mask Register Bits</entry> - </row> - - <row> - <entry>0x0f</entry> - <entry>read</entry> - <entry>Read All Mask Register Bits (only in Intel - 82374)</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - - <sect3> - <title>0xc0–0xdf DMA Controller #2 (Channels 4, 5, 6 and - 7)</title> - - <para>DMA Address and Count Registers</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>0xc0</entry> - <entry>write</entry> - <entry>Channel 4 starting address</entry> - </row> - - <row> - <entry>0xc0</entry> - <entry>read</entry> - <entry>Channel 4 current address</entry> - </row> - - <row> - <entry>0xc2</entry> - <entry>write</entry> - <entry>Channel 4 starting word count</entry> - </row> - - <row> - <entry>0xc2</entry> - <entry>read</entry> - <entry>Channel 4 remaining word count</entry> - </row> - - <row> - <entry>0xc4</entry> - <entry>write</entry> - <entry>Channel 5 starting address</entry> - </row> - - <row> - <entry>0xc4</entry> - <entry>read</entry> - <entry>Channel 5 current address</entry> - </row> - - <row> - <entry>0xc6</entry> - <entry>write</entry> - <entry>Channel 5 starting word count</entry> - </row> - - <row> - <entry>0xc6</entry> - <entry>read</entry> - <entry>Channel 5 remaining word count</entry> - </row> - - <row> - <entry>0xc8</entry> - <entry>write</entry> - <entry>Channel 6 starting address</entry> - </row> - - <row> - <entry>0xc8</entry> - <entry>read</entry> - <entry>Channel 6 current address</entry> - </row> - - <row> - <entry>0xca</entry> - <entry>write</entry> - <entry>Channel 6 starting word count</entry> - </row> - - <row> - <entry>0xca</entry> - <entry>read</entry> - <entry>Channel 6 remaining word count</entry> - </row> - - <row> - <entry>0xcc</entry> - <entry>write</entry> - <entry>Channel 7 starting address</entry> - </row> - - <row> - <entry>0xcc</entry> - <entry>read</entry> - <entry>Channel 7 current address</entry> - </row> - - <row> - <entry>0xce</entry> - <entry>write</entry> - <entry>Channel 7 starting word count</entry> - </row> - - <row> - <entry>0xce</entry> - <entry>read</entry> - <entry>Channel 7 remaining word count</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>DMA Command Registers</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>0xd0</entry> - <entry>write</entry> - <entry>Command Register</entry> - </row> - - <row> - <entry>0xd0</entry> - <entry>read</entry> - <entry>Status Register</entry> - </row> - - <row> - <entry>0xd2</entry> - <entry>write</entry> - <entry>Request Register</entry> - </row> - - <row> - <entry>0xd2</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0xd4</entry> - <entry>write</entry> - <entry>Single Mask Register Bit</entry> - </row> - - <row> - <entry>0xd4</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0xd6</entry> - <entry>write</entry> - <entry>Mode Register</entry> - </row> - - <row> - <entry>0xd6</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0xd8</entry> - <entry>write</entry> - <entry>Clear LSB/MSB Flip-Flop</entry> - </row> - - <row> - <entry>0xd8</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0xda</entry> - <entry>write</entry> - <entry>Master Clear/Reset</entry> - </row> - - <row> - <entry>0xda</entry> - <entry>read</entry> - <entry>Temporary Register (not present in Intel - 82374)</entry> - </row> - - <row> - <entry>0xdc</entry> - <entry>write</entry> - <entry>Clear Mask Register</entry> - </row> - - <row> - <entry>0xdc</entry> - <entry>read</entry> - <entry>-</entry> - </row> - - <row> - <entry>0xde</entry> - <entry>write</entry> - <entry>Write All Mask Register Bits</entry> - </row> - - <row> - <entry>0xdf</entry> - <entry>read</entry> - <entry>Read All Mask Register Bits (only in Intel - 82374)</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - - <sect3> - <title>0x80–0x9f DMA Page Registers</title> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>0x87</entry> - <entry>r/w</entry> - <entry>Channel 0 Low byte (23-16) page Register</entry> - </row> - - <row> - <entry>0x83</entry> - <entry>r/w</entry> - <entry>Channel 1 Low byte (23-16) page Register</entry> - </row> - - <row> - <entry>0x81</entry> - <entry>r/w</entry> - <entry>Channel 2 Low byte (23-16) page Register</entry> - </row> - - <row> - <entry>0x82</entry> - <entry>r/w</entry> - <entry>Channel 3 Low byte (23-16) page Register</entry> - </row> - - <row> - <entry>0x8b</entry> - <entry>r/w</entry> - <entry>Channel 5 Low byte (23-16) page Register</entry> - </row> - - <row> - <entry>0x89</entry> - <entry>r/w</entry> - <entry>Channel 6 Low byte (23-16) page Register</entry> - </row> - - <row> - <entry>0x8a</entry> - <entry>r/w</entry> - <entry>Channel 7 Low byte (23-16) page Register</entry> - </row> - - <row> - <entry>0x8f</entry> - <entry>r/w</entry> - <entry>Low byte page Refresh</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - - <sect3> - <title>0x400–0x4ff 82374 Enhanced DMA Registers</title> - - <para>The Intel 82374 EISA System Component (ESC) was introduced in - early 1996 and includes a DMA controller that provides a superset of - 8237 functionality as well as other PC-compatible core peripheral - components in a single package. This chip is targeted at both EISA - and PCI platforms, and provides modern DMA features like - scatter-gather, ring buffers as well as direct access by the system - DMA to all 32 bits of address space.</para> - - <para>If these features are used, code should also be included to - provide similar functionality in the previous 16 years worth of - PC-compatible computers. For compatibility reasons, some of the - 82374 registers must be programmed <emphasis>after</emphasis> - programming the traditional 8237 registers for each transfer. - Writing to a traditional 8237 register forces the contents of some - of the 82374 enhanced registers to zero to provide backward software - compatibility.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>0x401</entry> - <entry>r/w</entry> - <entry>Channel 0 High byte (bits 23-16) word count</entry> - </row> - - <row> - <entry>0x403</entry> - <entry>r/w</entry> - <entry>Channel 1 High byte (bits 23-16) word count</entry> - </row> - - <row> - <entry>0x405</entry> - <entry>r/w</entry> - <entry>Channel 2 High byte (bits 23-16) word count</entry> - </row> - - <row> - <entry>0x407</entry> - <entry>r/w</entry> - <entry>Channel 3 High byte (bits 23-16) word count</entry> - </row> - - <row> - <entry>0x4c6</entry> - <entry>r/w</entry> - <entry>Channel 5 High byte (bits 23-16) word count</entry> - </row> - - <row> - <entry>0x4ca</entry> - <entry>r/w</entry> - <entry>Channel 6 High byte (bits 23-16) word count</entry> - </row> - - <row> - <entry>0x4ce</entry> - <entry>r/w</entry> - <entry>Channel 7 High byte (bits 23-16) word count</entry> - </row> - - <row> - <entry>0x487</entry> - <entry>r/w</entry> - <entry>Channel 0 High byte (bits 31-24) page Register</entry> - </row> - - <row> - <entry>0x483</entry> - <entry>r/w</entry> - <entry>Channel 1 High byte (bits 31-24) page Register</entry> - </row> - - <row> - <entry>0x481</entry> - <entry>r/w</entry> - <entry>Channel 2 High byte (bits 31-24) page Register</entry> - </row> - - <row> - <entry>0x482</entry> - <entry>r/w</entry> - <entry>Channel 3 High byte (bits 31-24) page Register</entry> - </row> - - <row> - <entry>0x48b</entry> - <entry>r/w</entry> - <entry>Channel 5 High byte (bits 31-24) page Register</entry> - </row> - - <row> - <entry>0x489</entry> - <entry>r/w</entry> - <entry>Channel 6 High byte (bits 31-24) page Register</entry> - </row> - - <row> - <entry>0x48a</entry> - <entry>r/w</entry> - <entry>Channel 6 High byte (bits 31-24) page Register</entry> - </row> - - <row> - <entry>0x48f</entry> - <entry>r/w</entry> - <entry>High byte page Refresh</entry> - </row> - - <row> - <entry>0x4e0</entry> - <entry>r/w</entry> - <entry>Channel 0 Stop Register (bits 7-2)</entry> - </row> - - <row> - <entry>0x4e1</entry> - <entry>r/w</entry> - <entry>Channel 0 Stop Register (bits 15-8)</entry> - </row> - - <row> - <entry>0x4e2</entry> - <entry>r/w</entry> - <entry>Channel 0 Stop Register (bits 23-16)</entry> - </row> - - <row> - <entry>0x4e4</entry> - <entry>r/w</entry> - <entry>Channel 1 Stop Register (bits 7-2)</entry> - </row> - - <row> - <entry>0x4e5</entry> - <entry>r/w</entry> - <entry>Channel 1 Stop Register (bits 15-8)</entry> - </row> - - <row> - <entry>0x4e6</entry> - <entry>r/w</entry> - <entry>Channel 1 Stop Register (bits 23-16)</entry> - </row> - - <row> - <entry>0x4e8</entry> - <entry>r/w</entry> - <entry>Channel 2 Stop Register (bits 7-2)</entry> - </row> - - <row> - <entry>0x4e9</entry> - <entry>r/w</entry> - <entry>Channel 2 Stop Register (bits 15-8)</entry> - </row> - - <row> - <entry>0x4ea</entry> - <entry>r/w</entry> - <entry>Channel 2 Stop Register (bits 23-16)</entry> - </row> - - <row> - <entry>0x4ec</entry> - <entry>r/w</entry> - <entry>Channel 3 Stop Register (bits 7-2)</entry> - </row> - - <row> - <entry>0x4ed</entry> - <entry>r/w</entry> - <entry>Channel 3 Stop Register (bits 15-8)</entry> - </row> - - <row> - <entry>0x4ee</entry> - <entry>r/w</entry> - <entry>Channel 3 Stop Register (bits 23-16)</entry> - </row> - - <row> - <entry>0x4f4</entry> - <entry>r/w</entry> - <entry>Channel 5 Stop Register (bits 7-2)</entry> - </row> - - <row> - <entry>0x4f5</entry> - <entry>r/w</entry> - <entry>Channel 5 Stop Register (bits 15-8)</entry> - </row> - - <row> - <entry>0x4f6</entry> - <entry>r/w</entry> - <entry>Channel 5 Stop Register (bits 23-16)</entry> - </row> - - <row> - <entry>0x4f8</entry> - <entry>r/w</entry> - <entry>Channel 6 Stop Register (bits 7-2)</entry> - </row> - - <row> - <entry>0x4f9</entry> - <entry>r/w</entry> - <entry>Channel 6 Stop Register (bits 15-8)</entry> - </row> - - <row> - <entry>0x4fa</entry> - <entry>r/w</entry> - <entry>Channel 6 Stop Register (bits 23-16)</entry> - </row> - - <row> - <entry>0x4fc</entry> - <entry>r/w</entry> - <entry>Channel 7 Stop Register (bits 7-2)</entry> - </row> - - <row> - <entry>0x4fd</entry> - <entry>r/w</entry> - <entry>Channel 7 Stop Register (bits 15-8)</entry> - </row> - - <row> - <entry>0x4fe</entry> - <entry>r/w</entry> - <entry>Channel 7 Stop Register (bits 23-16)</entry> - </row> - - <row> - <entry>0x40a</entry> - <entry>write</entry> - <entry>Channels 0-3 Chaining Mode Register</entry> - </row> - - <row> - <entry>0x40a</entry> - <entry>read</entry> - <entry>Channel Interrupt Status Register</entry> - </row> - - <row> - <entry>0x4d4</entry> - <entry>write</entry> - <entry>Channels 4-7 Chaining Mode Register</entry> - </row> - - <row> - <entry>0x4d4</entry> - <entry>read</entry> - <entry>Chaining Mode Status</entry> - </row> - - <row> - <entry>0x40c</entry> - <entry>read</entry> - <entry>Chain Buffer Expiration Control Register</entry> - </row> - - <row> - <entry>0x410</entry> - <entry>write</entry> - <entry>Channel 0 Scatter-Gather Command Register</entry> - </row> - - <row> - <entry>0x411</entry> - <entry>write</entry> - <entry>Channel 1 Scatter-Gather Command Register</entry> - </row> - - <row> - <entry>0x412</entry> - <entry>write</entry> - <entry>Channel 2 Scatter-Gather Command Register</entry> - </row> - - <row> - <entry>0x413</entry> - <entry>write</entry> - <entry>Channel 3 Scatter-Gather Command Register</entry> - </row> - - <row> - <entry>0x415</entry> - <entry>write</entry> - <entry>Channel 5 Scatter-Gather Command Register</entry> - </row> - - <row> - <entry>0x416</entry> - <entry>write</entry> - <entry>Channel 6 Scatter-Gather Command Register</entry> - </row> - - <row> - <entry>0x417</entry> - <entry>write</entry> - <entry>Channel 7 Scatter-Gather Command Register</entry> - </row> - - <row> - <entry>0x418</entry> - <entry>read</entry> - <entry>Channel 0 Scatter-Gather Status Register</entry> - </row> - - <row> - <entry>0x419</entry> - <entry>read</entry> - <entry>Channel 1 Scatter-Gather Status Register</entry> - </row> - - <row> - <entry>0x41a</entry> - <entry>read</entry> - <entry>Channel 2 Scatter-Gather Status Register</entry> - </row> - - <row> - <entry>0x41b</entry> - <entry>read</entry> - <entry>Channel 3 Scatter-Gather Status Register</entry> - </row> - - <row> - <entry>0x41d</entry> - <entry>read</entry> - <entry>Channel 5 Scatter-Gather Status Register</entry> - </row> - - <row> - <entry>0x41e</entry> - <entry>read</entry> - <entry>Channel 5 Scatter-Gather Status Register</entry> - </row> - - <row> - <entry>0x41f</entry> - <entry>read</entry> - <entry>Channel 7 Scatter-Gather Status Register</entry> - </row> - - <row> - <entry>0x420-0x423</entry> - <entry>r/w</entry> - <entry>Channel 0 Scatter-Gather Descriptor Table Pointer - Register</entry> - </row> - - <row> - <entry>0x424-0x427</entry> - <entry>r/w</entry> - <entry>Channel 1 Scatter-Gather Descriptor Table Pointer - Register</entry> - </row> - - <row> - <entry>0x428-0x42b</entry> - <entry>r/w</entry> - <entry>Channel 2 Scatter-Gather Descriptor Table Pointer - Register</entry> - </row> - - <row> - <entry>0x42c-0x42f</entry> - <entry>r/w</entry> - <entry>Channel 3 Scatter-Gather Descriptor Table Pointer - Register</entry> - </row> - - <row> - <entry>0x434-0x437</entry> - <entry>r/w</entry> - <entry>Channel 5 Scatter-Gather Descriptor Table Pointer - Register</entry> - </row> - - <row> - <entry>0x438-0x43b</entry> - <entry>r/w</entry> - <entry>Channel 6 Scatter-Gather Descriptor Table Pointer - Register</entry> - </row> - - <row> - <entry>0x43c-0x43f</entry> - <entry>r/w</entry> - <entry>Channel 7 Scatter-Gather Descriptor Table Pointer - Register</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - </sect2> - </sect1> - - <sect1 id="internals-vm"> - <title>The FreeBSD VM System</title> - - <para><emphasis>Contributed by &a.dillon;. 6 Feb 1999</emphasis></para> - - <sect2> - <title>Management of physical - memory—<literal>vm_page_t</literal></title> - - <para>Physical memory is managed on a page-by-page basis through the - <literal>vm_page_t</literal> structure. Pages of physical memory are - categorized through the placement of their respective - <literal>vm_page_t</literal> structures on one of several paging - queues.</para> - - <para>A page can be in a wired, active, inactive, cache, or free state. - Except for the wired state, the page is typically placed in a doubly - link list queue representing the state that it is in. Wired pages - are not placed on any queue.</para> - - <para>FreeBSD implements a more involved paging queue for cached and - free pages in order to implement page coloring. Each of these states - involves multiple queues arranged according to the size of the - processor's L1 and L2 caches. When a new page needs to be allocated, - FreeBSD attempts to obtain one that is reasonably well aligned from - the point of view of the L1 and L2 caches relative to the VM object - the page is being allocated for.</para> - - <para>Additionally, a page may be held with a reference count or locked - with a busy count. The VM system also implements an “ultimate - locked” state for a page using the PG_BUSY bit in the page's - flags.</para> - - <para>In general terms, each of the paging queues operates in a LRU - fashion. A page is typically placed in a wired or active state - initially. When wired, the page is usually associated with a page - table somewhere. The VM system ages the page by scanning pages in a - more active paging queue (LRU) in order to move them to a less-active - paging queue. Pages that get moved into the cache are still - associated with a VM object but are candidates for immediate reuse. - Pages in the free queue are truly free. FreeBSD attempts to minimize - the number of pages in the free queue, but a certain minimum number of - truly free pages must be maintained in order to accommodate page - allocation at interrupt time.</para> - - <para>If a process attempts to access a page that does not exist in its - page table but does exist in one of the paging queues ( such as the - inactive or cache queues), a relatively inexpensive page reactivation - fault occurs which causes the page to be reactivated. If the page - does not exist in system memory at all, the process must block while - the page is brought in from disk.</para> - - <para>FreeBSD dynamically tunes its paging queues and attempts to - maintain reasonable ratios of pages in the various queues as well as - attempts to maintain a reasonable breakdown of clean vs dirty pages. - The amount of rebalancing that occurs depends on the system's memory - load. This rebalancing is implemented by the pageout daemon and - involves laundering dirty pages (syncing them with their backing - store), noticing when pages are activity referenced (resetting their - position in the LRU queues or moving them between queues), migrating - pages between queues when the queues are out of balance, and so forth. - FreeBSD's VM system is willing to take a reasonable number of - reactivation page faults to determine how active or how idle a page - actually is. This leads to better decisions being made as to when to - launder or swap-out a page.</para> - </sect2> - - <sect2> - <title>The unified buffer - cache—<literal>vm_object_t</literal></title> - - <para>FreeBSD implements the idea of a generic “VM object”. - VM objects can be associated with backing store of various - types—unbacked, swap-backed, physical device-backed, or - file-backed storage. Since the filesystem uses the same VM objects to - manage in-core data relating to files, the result is a unified buffer - cache.</para> - - <para>VM objects can be <emphasis>shadowed</emphasis>. That is, they - can be stacked on top of each other. For example, you might have a - swap-backed VM object stacked on top of a file-backed VM object in - order to implement a MAP_PRIVATE mmap()ing. This stacking is also - used to implement various sharing properties, including, - copy-on-write, for forked address spaces.</para> - - <para>It should be noted that a <literal>vm_page_t</literal> can only be - associated with one VM object at a time. The VM object shadowing - implements the perceived sharing of the same page across multiple - instances.</para> - </sect2> - - <sect2> - <title>Filesystem I/O—<literal>struct buf</literal></title> - - <para>vnode-backed VM objects, such as file-backed objects, generally - need to maintain their own clean/dirty info independent from the VM - system's idea of clean/dirty. For example, when the VM system decides - to synchronize a physical page to its backing store, the VM system - needs to mark the page clean before the page is actually written to - its backing s tore. Additionally, filesystems need to be able to map - portions of a file or file metadata into KVM in order to operate on - it.</para> - - <para>The entities used to manage this are known as filesystem buffers, - <literal>struct buf</literal>'s, and also known as - <literal>bp</literal>'s. When a filesystem needs to operate on a - portion of a VM object, it typically maps part of the object into a - struct buf and the maps the pages in the struct buf into KVM. In the - same manner, disk I/O is typically issued by mapping portions of - objects into buffer structures and then issuing the I/O on the buffer - structures. The underlying vm_page_t's are typically busied for the - duration of the I/O. Filesystem buffers also have their own notion of - being busy, which is useful to filesystem driver code which would - rather operate on filesystem buffers instead of hard VM pages.</para> - - <para>FreeBSD reserves a limited amount of KVM to hold mappings from - struct bufs, but it should be made clear that this KVM is used solely - to hold mappings and does not limit the ability to cache data. - Physical data caching is strictly a function of - <literal>vm_page_t</literal>'s, not filesystem buffers. However, - since filesystem buffers are used placehold I/O, they do inherently - limit the amount of concurrent I/O possible. As there are usually a - few thousand filesystem buffers available, this is not usually a - problem.</para> - </sect2> - - <sect2> - <title>Mapping Page Tables - vm_map_t, vm_entry_t</title> - - <para>FreeBSD separates the physical page table topology from the VM - system. All hard per-process page tables can be reconstructed on the - fly and are usually considered throwaway. Special page tables such as - those managing KVM are typically permanently preallocated. These page - tables are not throwaway.</para> - - <para>FreeBSD associates portions of vm_objects with address ranges in - virtual memory through <literal>vm_map_t</literal> and - <literal>vm_entry_t</literal> structures. Page tables are directly - synthesized from the - <literal>vm_map_t</literal>/<literal>vm_entry_t</literal>/ - <literal>vm_object_t</literal> hierarchy. Remember when I mentioned - that physical pages are only directly associated with a - <literal>vm_object</literal>. Well, that isn't quite true. - <literal>vm_page_t</literal>'s are also linked into page tables that - they are actively associated with. One <literal>vm_page_t</literal> - can be linked into several <emphasis>pmaps</emphasis>, as page tables - are called. However, the hierarchical association holds so all - references to the same page in the same object reference the same - <literal>vm_page_t</literal> and thus give us buffer cache unification - across the board.</para> - </sect2> - - <sect2> - <title>KVM Memory Mapping</title> - - <para>FreeBSD uses KVM to hold various kernel structures. The single - largest entity held in KVM is the filesystem buffer cache. That is, - mappings relating to <literal>struct buf</literal> entities.</para> - - <para>Unlike Linux, FreeBSD does NOT map all of physical memory into - KVM. This means that FreeBSD can handle memory configurations up to - 4G on 32 bit platforms. In fact, if the mmu were capable of it, - FreeBSD could theoretically handle memory configurations up to 8TB on - a 32 bit platform. However, since most 32 bit platforms are only - capable of mapping 4GB of ram, this is a moot point.</para> - - <para>KVM is managed through several mechanisms. The main mechanism - used to manage KVM is the <emphasis>zone allocator</emphasis>. The - zone allocator takes a chunk of KVM and splits it up into - constant-sized blocks of memory in order to allocate a specific type - of structure. You can use <command>vmstat -m</command> to get an - overview of current KVM utilization broken down by zone.</para> - </sect2> - - <sect2> - <title>Tuning the FreeBSD VM system</title> - - <para>A concerted effort has been made to make the FreeBSD kernel - dynamically tune itself. Typically you do not need to mess with - anything beyond the <literal>maxusers</literal> and - <literal>NMBCLUSTERS</literal> kernel config options. That is, kernel - compilation options specified in (typically) - <filename>/usr/src/sys/i386/conf/<replaceable>CONFIG_FILE</replaceable></filename>. - A description of all available kernel configuration options can be - found in <filename>/usr/src/sys/i386/conf/LINT</filename>.</para> - - <para>In a large system configuration you may wish to increase - <literal>maxusers</literal>. Values typically range from 10 to 128. - Note that raising <literal>maxusers</literal> too high can cause the - system to overflow available KVM resulting in unpredictable operation. - It is better to leave maxusers at some reasonable number and add other - options, such as <literal>NMBCLUSTERS</literal>, to increase specific - resources.</para> - - <para>If your system is going to use the network heavily, you may want - to increase <literal>NMBCLUSTERS</literal>. Typical values range from - 1024 to 4096.</para> - - <para>The <literal>NBUF</literal> parameter is also traditionally used - to scale the system. This parameter determines the amount of KVA the - system can use to map filesystem buffers for I/O. Note that this - parameter has nothing whatsoever to do with the unified buffer cache! - This parameter is dynamically tuned in 3.0-CURRENT and later kernels - and should generally not be adjusted manually. We recommend that you - <emphasis>not</emphasis> try to specify an <literal>NBUF</literal> - parameter. Let the system pick it. Too small a value can result in - extremely inefficient filesystem operation while too large a value can - starve the page queues by causing too many pages to become wired - down.</para> - - <para>By default, FreeBSD kernels are not optimized. You can set - debugging and optimization flags with the - <literal>makeoptions</literal> directive in the kernel configuration. - Note that you should not use <option>-g</option> unless you can - accommodate the large (typically 7 MB+) kernels that result.</para> - - <programlisting>makeoptions DEBUG="-g" -makeoptions COPTFLAGS="-O2 -pipe"</programlisting> - - <para>Sysctl provides a way to tune kernel parameters at run-time. You - typically do not need to mess with any of the sysctl variables, - especially the VM related ones.</para> - - <para>Run time VM and system tuning is relatively straightforward. - First, use softupdates on your UFS/FFS filesystems whenever possible. - <filename>/usr/src/contrib/sys/softupdates/README</filename> contains - instructions (and restrictions) on how to configure it up.</para> - - <para>Second, configure sufficient swap. You should have a swap - partition configured on each physical disk, up to four, even on your - “work” disks. You should have at least 2x the swap space - as you have main memory, and possibly even more if you do not have a - lot of memory. You should also size your swap partition based on the - maximum memory configuration you ever intend to put on the machine so - you do not have to repartition your disks later on. If you want to be - able to accommodate a crash dump, your first swap partition must be at - least as large as main memory and <filename>/var/crash</filename> must - have sufficient free space to hold the dump.</para> - - <para>NFS-based swap is perfectly acceptable on -4.x or later systems, - but you must be aware that the NFS server will take the brunt of the - paging load.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/introduction/chapter.sgml b/en/handbook/introduction/chapter.sgml deleted file mode 100644 index ca85db65e7..0000000000 --- a/en/handbook/introduction/chapter.sgml +++ /dev/null @@ -1,607 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.13 1999-06-13 16:18:55 nik Exp $ ---> - -<chapter id="introduction"> - <title>Introduction</title> - - <para>FreeBSD is a 4.4BSD-Lite2 based operating system for Intel architecture - (x86) and DEC Alpha based computer systems. For an overview of FreeBSD, see - <link linkend="nutshell">FreeBSD in a nutshell</link>. For a history of - the project, read <link linkend="history">a brief history of FreeBSD</link>. - To see a description of the latest release, read <link - linkend="relnotes">about the current release</link>. If you are - interested in contributing something to the FreeBSD project (code, - equipment, sacks of unmarked bills), please see about <link - linkend="contrib">contributing to FreeBSD</link>.</para> - - <sect1 id="nutshell"> - <title>FreeBSD in a Nutshell</title> - - <para>FreeBSD is a state of the art operating system for computer - systems based on both the Intel CPU architecture, which includes the - 386 and 486 and Pentium processors (both SX and DX versions) and the DEC - Alpha architecture. Intel compatible CPUs from AMD to Cyrix are - supported as well. FreeBSD provides you with many advanced features - previously available only on much more expensive computers. - These features include:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Preemptive multitasking</emphasis> with dynamic - priority adjustment to ensure smooth and fair sharing of the - computer between applications and users.</para> - </listitem> - - <listitem> - <para><emphasis>Multiuser</emphasis> access means that many people can - use a FreeBSD system simultaneously for a variety of things. System - peripherals such as printers and tape drives are also properly - SHARED BETWEEN ALL users on the system.</para> - </listitem> - - <listitem> - <para>Complete <emphasis>TCP/IP networking</emphasis> including SLIP, - PPP, NFS and NIS support. This means that your FreeBSD machine can - inter-operate easily with other systems as well act as an enterprise - server, providing vital functions such as NFS (remote file access) - and e-mail services or putting your organization on the Internet - with WWW, ftp, routing and firewall (security) services.</para> - </listitem> - - <listitem> - <para><emphasis>Memory protection</emphasis> ensures that applications - (or users) cannot interfere with each other. One application - crashing will not affect others in any way.</para> - </listitem> - - <listitem> - <para>FreeBSD is a <emphasis>32-bit</emphasis> operating system and - was designed as such from the ground up.</para> - </listitem> - - <listitem> - <para>The industry standard <emphasis>X Window System</emphasis> - (X11R6) provides a graphical user interface (GUI) for the cost of a - common VGA card and monitor and comes with full sources.</para> - </listitem> - - <listitem> - <para><emphasis>Binary compatibility</emphasis> with many programs - built for SCO, BSDI, NetBSD, Linux and 386BSD.</para> - </listitem> - - <listitem> - <para>Hundreds of <emphasis>ready-to-run</emphasis> applications are - available from the FreeBSD <emphasis>ports</emphasis> and - <emphasis>packages</emphasis> collection. Why search the net when - you can find it all right here?</para> - </listitem> - - <listitem> - <para>Thousands of additional and <emphasis>easy-to-port</emphasis> - applications available on the Internet. FreeBSD is source code - compatible with most popular commercial Unix systems and thus most - applications require few, if any, changes to compile.</para> - </listitem> - - <listitem> - <para>Demand paged <emphasis>virtual memory</emphasis> and - “merged VM/buffer cache” design efficiently satisfies - applications with large appetites for memory while still maintaining - interactive response to other users.</para> - </listitem> - - <listitem> - <para><emphasis>Shared libraries</emphasis> (the Unix equivalent of - MS-Windows DLLs) provide for efficient use of disk space and - memory.</para> - </listitem> - - <listitem> - <para>A full complement of <emphasis>C</emphasis>, - <emphasis>C++</emphasis> and <emphasis>Fortran</emphasis> - development tools. Many additional languages for advanced research - and development are also available in the ports and packages - collection.</para> - </listitem> - - <listitem> - <para><emphasis>Source code</emphasis> for the entire system means you - have the greatest degree of control over your environment. Why be - locked into a proprietary solution and at the mercy of your vendor - when you can have a truly Open System?</para> - </listitem> - - <listitem> - <para>Extensive <emphasis>on-line documentation</emphasis>.</para> - </listitem> - - <listitem> - <para><emphasis>And many more!</emphasis></para> - </listitem> - </itemizedlist> - - <para>FreeBSD is based on the 4.4BSD-Lite2 release from Computer Systems - Research Group (CSRG) at the University of California at Berkeley, and - carries on the distinguished tradition of BSD systems development. In - addition to the fine work provided by CSRG, the FreeBSD Project has put - in many thousands of hours in fine tuning the system for maximum - performance and reliability in real-life load situations. As many of - the commercial giants struggle to field PC operating systems with such - features, performance and reliability, FreeBSD can offer them - <emphasis>now</emphasis>!</para> - - <para>The applications to which FreeBSD can be put are truly limited only - by your own imagination. From software development to factory - automation, inventory control to azimuth correction of remote satellite - antennae; if it can be done with a commercial UNIX product then it is - more than likely that you can do it with FreeBSD, too! FreeBSD also - benefits significantly from the literally thousands of high quality - applications developed by research centers and universities around the - world, often available at little to no cost. Commercial applications are - also available and appearing in greater numbers every day.</para> - - <para>Because the source code for FreeBSD itself is generally available, - the system can also be customized to an almost unheard of degree for - special applications or projects, and in ways not generally possible - with operating systems from most major commercial vendors. Here is just - a sampling of some of the applications in which people are currently - using FreeBSD:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Internet Services:</emphasis> The robust TCP/IP - networking built into FreeBSD makes it an ideal platform for a - variety of Internet services such as:</para> - - <itemizedlist> - <listitem> - <para>FTP servers</para> - </listitem> - - <listitem> - <para>World Wide Web servers</para> - </listitem> - - <listitem> - <para>Gopher servers</para> - </listitem> - - <listitem> - <para>Electronic Mail servers</para> - </listitem> - - <listitem> - <para>USENET News</para> - </listitem> - - <listitem> - <para>Bulletin Board Systems</para> - </listitem> - - <listitem> - <para>And more...</para> - </listitem> - </itemizedlist> - - <para>You can easily start out small with an inexpensive 386 class PC - and upgrade as your enterprise grows.</para> - </listitem> - - <listitem> - <para><emphasis>Education:</emphasis> Are you a student of computer - science or a related engineering field? There is no better way of - learning about operating systems, computer architecture and - networking than the hands on, under the hood experience that FreeBSD - can provide. A number of freely available CAD, mathematical and - graphic design packages also make it highly useful to those whose - primary interest in a computer is to get <emphasis>other</emphasis> - work done!</para> - </listitem> - - <listitem> - <para><emphasis>Research:</emphasis> With source code for the entire - system available, FreeBSD is an excellent platform for research in - operating systems as well as other branches of computer science. - FreeBSD's freely available nature also makes it possible for remote - groups to collaborate on ideas or shared development without having - to worry about special licensing agreements or limitations on what - may be discussed in open forums.</para> - </listitem> - - <listitem> - <para><emphasis>Networking:</emphasis> Need a new router? A name - server (DNS)? A firewall to keep people out of your internal - network? FreeBSD can easily turn that unused 386 or 486 PC sitting - in the corner into an advanced router with sophisticated packet - filtering capabilities.</para> - </listitem> - - <listitem> - <para><emphasis>X Window workstation:</emphasis> FreeBSD is a fine - choice for an inexpensive X terminal solution, either using the - freely available XFree86 server or one of the excellent commercial - servers provided by X Inside. Unlike an X terminal, FreeBSD allows - many applications to be run locally, if desired, thus relieving the - burden on a central server. FreeBSD can even boot - “diskless”, making individual workstations even cheaper - and easier to administer.</para> - </listitem> - - <listitem> - <para><emphasis>Software Development:</emphasis> The basic FreeBSD - system comes with a full complement of development tools including - the renowned GNU C/C++ compiler and debugger.</para> - </listitem> - </itemizedlist> - - <para>FreeBSD is available in both source and binary form on CDROM and via - anonymous ftp. See <link linkend="mirrors">Obtaining FreeBSD</link> - for more details.</para> - </sect1> - - <sect1 id="history"> - <title>A Brief History of FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;</emphasis>.</para> - - <para>The FreeBSD project had its genesis in the early part of 1993, - partially as an outgrowth of the “Unofficial 386BSD - Patchkit” by the patchkit's last 3 coordinators: Nate Williams, - Rod Grimes and myself.</para> - - <para>Our original goal was to produce an intermediate snapshot of 386BSD - in order to fix a number of problems with it that the patchkit mechanism - just was not capable of solving. Some of you may remember the early - working title for the project being “386BSD 0.5” or - “386BSD Interim” in reference to that fact.</para> - - <para>386BSD was Bill Jolitz's operating system, which had been up to that - point suffering rather severely from almost a year's worth of neglect. - As the patchkit swelled ever more uncomfortably with each passing day, - we were in unanimous agreement that something had to be done and decided - to try and assist Bill by providing this interim “cleanup” - snapshot. Those plans came to a rude halt when Bill Jolitz suddenly - decided to withdraw his sanction from the project and without any clear - indication of what would be done instead.</para> - - <para>It did not take us long to decide that the goal remained worthwhile, - even without Bill's support, and so we adopted the name - “FreeBSD”, coined by David Greenman. Our initial objectives - were set after consulting with the system's current users and, once it - became clear that the project was on the road to perhaps even becoming a - reality, I contacted Walnut Creek CDROM with an eye towards improving - FreeBSD's distribution channels for those many unfortunates without easy - access to the Internet. Walnut Creek CDROM not only supported the idea - of distributing FreeBSD on CD but went so far as to provide the project - with a machine to work on and a fast Internet connection. Without - Walnut Creek CDROM's almost unprecedented degree of faith in what was, - at the time, a completely unknown project, it is quite unlikely that - FreeBSD would have gotten as far, as fast, as it has today.</para> - - <para>The first CDROM (and general net-wide) distribution was FreeBSD 1.0, - released in December of 1993. This was based on the 4.3BSD-Lite - (“Net/2”) tape from U.C. Berkeley, with many components also - provided by 386BSD and the Free Software Foundation. It was a fairly - reasonable success for a first offering, and we followed it with the - highly successful FreeBSD 1.1 release in May of 1994.</para> - - <para>Around this time, some rather unexpected storm clouds formed on the - horizon as Novell and U.C. Berkeley settled their long-running lawsuit - over the legal status of the Berkeley Net/2 tape. A condition of that - settlement was U.C. Berkeley's concession that large parts of Net/2 were - “encumbered” code and the property of Novell, who had in - turn acquired it from AT&T some time previously. What Berkeley got - in return was Novell's “blessing” that the 4.4BSD-Lite - release, when it was finally released, would be declared unencumbered - and all existing Net/2 users would be strongly encouraged to switch. - This included FreeBSD, and the project was given until the end of July - 1994 to stop shipping its own Net/2 based product. Under the terms of - that agreement, the project was allowed one last release before the - deadline, that release being FreeBSD 1.1.5.1.</para> - - <para>FreeBSD then set about the arduous task of literally re-inventing - itself from a completely new and rather incomplete set of 4.4BSD-Lite - bits. The “Lite” releases were light in part because - Berkeley's CSRG had removed large chunks of code required for actually - constructing a bootable running system (due to various legal - requirements) and the fact that the Intel port of 4.4 was highly - incomplete. It took the project until November of 1994 to make this - transition, at which point it released FreeBSD 2.0 to the net - and on CDROM (in late December). Despite being still more than a little - rough around the edges, the release was a significant success and was - followed by the more robust and easier to install FreeBSD 2.0.5 release - in June of 1995.</para> - - <para>We released FreeBSD 2.1.5 in August of 1996, and it appeared to be - popular enough among the ISP and commercial communities that another - release along the 2.1-stable branch was merited. This was FreeBSD - 2.1.7.1, released in February 1997 and capping the end of mainstream - development on 2.1-stable. Now in maintenance mode, only security - enhancements and other critical bug fixes will be done on this branch - (RELENG_2_1_0).</para> - - <para>FreeBSD 2.2 was branched from the development mainline - (“-current”) in November 1996 as the RELENG_2_2 branch, and - the first full release (2.2.1) was released in April, 1997. Further - releases along the 2.2 branch were done in the Summer and Fall of '97, - the latest being 2.2.7 which appeared in late July of '98. The first - official 3.0 release appeared in October, 1998 and the last release on - the 2.2 branch, 2.2.8, appeared in November, 1998.</para> - - <para>The tree branched again on Jan 20, 1999. This led to 4.0-current - and a 3.x-stable branch, from which 3.1 was released on February - 15th, 1999 and 3.2 was released on May 15, 1999.</para> - - <para>Long term development projects will continue to take place in the - 4.0-current branch and SNAPshot releases of 4.0 on CDROM (and, of - course, on the net).</para> - </sect1> - - <sect1 id="goals"> - <title>FreeBSD Project Goals</title> - - <para><emphasis>Contributed by &a.jkh;</emphasis>.</para> - - <para>The goals of the FreeBSD Project are to provide software that may be - used for any purpose and without strings attached. Many of us have a - significant investment in the code (and project) and would certainly not - mind a little financial compensation now and then, but we are definitely - not prepared to insist on it. We believe that our first and foremost - “mission” is to provide code to any and all comers, and for - whatever purpose, so that the code gets the widest possible use and - provides the widest possible benefit. This is, I believe, one of the - most fundamental goals of Free Software and one that we enthusiastically - support.</para> - - <para>That code in our source tree which falls under the GNU General Public - License (GPL) or Library General Public License (LGPL) comes with slightly - more strings attached, though at least on the side of enforced access - rather than the usual opposite. Due to the additional complexities that - can evolve in the commercial use of GPL software, we do, however, - endeavor to replace such software with submissions under the more - relaxed BSD copyright when reasonable to do so.</para> - </sect1> - - <sect1 id="development"> - <title>The FreeBSD Development Model</title> - - <para><emphasis>Contributed by &a.asami;</emphasis>.</para> - - <para>The development of FreeBSD is a very open and flexible process, - FreeBSD being literally built from the contributions of hundreds of - people around the world, as can be seen from our <link - linkend="staff">list of contributors</link>. We are constantly on the - lookout for new developers and ideas, and those interested in becoming - more closely involved with the project need simply contact us at the - &a.hackers;. Those who prefer to work more independently are also - accommodated, and they are free to use our FTP facilities at <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming">ftp.FreeBSD.org</ulink> - to distribute their own patches or work-in-progress sources. The - &a.announce; is also available to those wishing to make other FreeBSD - users aware of major areas of work.</para> - - <para>Useful things to know about the FreeBSD project and its development - process, whether working independently or in close cooperation:</para> - - <variablelist> - <varlistentry> - <term>The CVS repository<anchor - id="development-cvs-repository"></term> - - <listitem> - <para>The central source tree for FreeBSD is maintained by <ulink - URL="http://www.cyclic.com/cyclic-pages/CVS-sheet.html">CVS</ulink> - (Concurrent Version System), a freely available source code - control tool which comes bundled with FreeBSD. The primary <ulink - URL="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVS - repository</ulink> resides on a machine in Concord CA, USA from - where it is replicated to numerous mirror machines throughout the - world. The CVS tree, as well as the <link - linkend="current">-current</link> and <link - linkend="stable">-stable</link> trees which are checked out of - it, can be easily replicated to your own machine as well. Please - refer to the <link linkend="synching">Synchronizing your source - tree</link> section for more information on doing this.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The committers list<anchor id="development-committers"></term> - - <listitem> - <para>The <link linkend="staff-committers">committers</link> are the - people who have <emphasis>write</emphasis> access to the CVS tree, - and are thus authorized to make modifications to the FreeBSD - source (the term “committer” comes from the - &man.cvs.1; <command>commit</command> command, which is used - to bring new changes into the CVS repository). The best way of - making submissions for review by the committers list is to use the - &man.send-pr.1; command, though if something appears to be - jammed in the system then you may also reach them by sending mail - to <email>committers@FreeBSD.org</email>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The FreeBSD core team<anchor id="development-core"></term> - - <listitem> - <para>The <link linkend="staff-core">FreeBSD core team</link> would - be equivalent to the board of directors if the FreeBSD Project - were a company. The primary task of the core team is to make sure - the project, as a whole, is in good shape and is heading in the - right directions. Inviting dedicated and responsible developers - to join our group of committers is one of the functions of the - core team, as is the recruitment of new core team members as - others move on. Most current members of the core team started as - committers whose addiction to the project got the better of - them.</para> - - <para>Some core team members also have specific <link - linkend="staff-who">areas of responsibility</link>, meaning that - they are committed to ensuring that some large portion of the - system works as advertised.</para> - - <note> - <para>Most members of the core team are volunteers when it comes - to FreeBSD development and do not benefit from the project - financially, so “commitment” should also not be - misconstrued as meaning “guaranteed support.” The - “board of directors” analogy above is not actually - very accurate, and it may be more suitable to say that these are - the people who gave up their lives in favor of FreeBSD against - their better judgement! <!-- smiley - --><emphasis>;)</emphasis></para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>Outside contributors</term> - - <listitem> - <para>Last, but definitely not least, the largest group of - developers are the users themselves who provide feedback and - bug-fixes to us on an almost constant basis. The primary way of - keeping in touch with FreeBSD's more non-centralized development - is to subscribe to the &a.hackers; (see <link - linkend="eresources-mail">mailing list info</link>) where such - things are discussed.</para> - - <para><link linkend="contrib-additional">The list</link> of those - who have contributed something which made its way into our source - tree is a long and growing one, so why not join it by contributing - something back to FreeBSD today? <!-- smiley - --><emphasis>:-)</emphasis></para> - - <para>Providing code is not the only way of contributing to the - project; for a more complete list of things that need doing, - please refer to the <link linkend="contrib">how to - contribute</link> section in this handbook.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In summary, our development model is organized as a loose set of - concentric circles. The centralized model is designed for the - convenience of the <emphasis>users</emphasis> of FreeBSD, who are - thereby provided with an easy way of tracking one central code base, not - to keep potential contributors out! Our desire is to present a stable - operating system with a large set of coherent <link - linkend="ports">application programs</link> that the users can easily - install and use, and this model works very well in accomplishing - that.</para> - - <para>All we ask of those who would join us as FreeBSD developers is some - of the same dedication its current people have to its continued - success!</para> - </sect1> - - <sect1 id="relnotes"> - <title>About the Current Release</title> - - <para>FreeBSD is a freely available, full source 4.4BSD-Lite2 based release - for Intel i386/i486/Pentium/PentiumPro/Pentium II (or compatible) and DEC - Alpha based computer systems. It is based primarily on software from U.C. - Berkeley's CSRG group, with some enhancements from NetBSD, OpenBSD, 386BSD, - and the Free Software Foundation.</para> - - <para>Since our release of FreeBSD 2.0 in late 94, the performance, - feature set, and stability of FreeBSD has improved dramatically. The - largest change is a revamped virtual memory system with a merged VM/file - buffer cache that not only increases performance, but reduces FreeBSD's - memory footprint, making a 5MB configuration a more acceptable minimum. - Other enhancements include full NIS client and server support, - transaction TCP support, dial-on-demand PPP, an improved SCSI subsystem, - ISDN support, support for ATM, FDDI and Fast Ethernet (100Mbit) - adapters, improved support for the Adaptec 2940 (WIDE and narrow) and - many hundreds of bug fixes.</para> - - <para>We have also taken the comments and suggestions of many of our users - to heart and have attempted to provide what we hope is a more sane and - easily understood installation process. Your feedback on this - (constantly evolving) process is especially welcome!</para> - - <para>In addition to the base distributions, FreeBSD offers a new ported - software collection with hundreds of commonly sought-after programs. At - the end of April 1999 there were more than 2300 ports! The list of - ports ranges from http (WWW) servers, to games, languages, editors and - almost everything in between. The entire ports collection requires - approximately 50MB of storage, all ports being expressed as - “deltas” to their original sources. This makes it much - easier for us to update ports, and greatly reduces the disk space - demands made by the older 1.0 ports collection. To compile a port, you - simply change to the directory of the program you wish to install, type - <command>make all</command> followed by <command>make install</command> - after successful compilation and let the system do the rest. The full - original distribution for each port you build is retrieved dynamically - off the CDROM or a local ftp site, so you need only enough disk space to - build the ports you want. (Almost) every port is also provided as a - pre-compiled “package” which can be installed with a simple - command (pkg_add) by those who do not wish to compile their own ports - from source.</para> - - <para>A number of additional documents which you may find very helpful in - the process of installing and using FreeBSD may now also be found in the - <filename>/usr/share/doc</filename> directory on any machine running - FreeBSD 2.1 or later. You may view the locally installed manuals with - any HTML capable browser using the following URLs:</para> - - <variablelist> - <varlistentry> - <term>The FreeBSD handbook</term> - - <listitem> - <para><ulink - URL="file:/usr/share/doc/handbook/handbook.html">file:/usr/share/doc/handbook/handbook.html</ulink></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The FreeBSD FAQ</term> - - <listitem> - <para><ulink - URL="file:/usr/share/doc/FAQ/FAQ.html">file:/usr/share/doc/FAQ/FAQ.html</ulink></para> - </listitem> - </varlistentry> - </variablelist> - - <para>You can also visit the master (and most frequently updated) - copies at <ulink - URL="http://www.FreeBSD.org">http://www.FreeBSD.org</ulink>.</para> - - <para>The core of FreeBSD does not contain DES code which would inhibit - its being exported outside the United States. There is an add-on - package to the core distribution, for use only in the United States, - that contains the programs that normally use DES. The auxiliary - packages provided separately can be used by anyone. A freely (from - outside the U.S.) exportable European distribution of DES for our - non-U.S. users also exists and is described in the <ulink - URL="../FAQ/FAQ.html">FreeBSD FAQ</ulink>.</para> - - <para>If password security for FreeBSD is all you need, and you have no - requirement for copying encrypted passwords from different hosts (Suns, - DEC machines, etc) into FreeBSD password entries, then FreeBSD's MD5 - based security may be all you require! We feel that our default security - model is more than a match for DES, and without any messy export issues - to deal with. If you are outside (or even inside) the U.S., give it a - try!</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/kernelconfig/chapter.sgml b/en/handbook/kernelconfig/chapter.sgml deleted file mode 100644 index 2b6e7bebc7..0000000000 --- a/en/handbook/kernelconfig/chapter.sgml +++ /dev/null @@ -1,1877 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.18 1999-08-05 20:48:14 nik Exp $ ---> - -<chapter id="kernelconfig"> - <title>Configuring the FreeBSD Kernel</title> - - <para><emphasis>Contributed by &a.jehamby;. 6 October - 1995.</emphasis></para> - - <para>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.</para> - - <sect1> - <title>Why Build a Custom Kernel?</title> - - <para>Building a custom kernel is one of the most important rites of - passage every Unix system administrator must endure. This process, - while time-consuming, will provide many benefits to your FreeBSD system. - Unlike the <filename>GENERIC</filename> 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 - <emphasis>your</emphasis> PC's hardware. This has a number of - benefits:</para> - - <itemizedlist> - <listitem> - <para>It will take less time to boot because it does not have to spend - time probing for hardware which you do not have.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>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 - <emphasis>not</emphasis> present in the GENERIC kernel.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="kernelconfig-building"> - <title>Building and Installing a Custom Kernel</title> - - <para>First, let us take a quick tour of the kernel build directory. All - directories mentioned will be relative to the main - <filename>/usr/src/sys</filename> directory, which is also accessible - through <filename>/sys</filename>. There are a number of subdirectories - here representing different parts of the kernel, but the most important, - for our purposes, are <filename>i386/conf</filename>, where you will - edit your custom kernel configuration, and <filename>compile</filename>, - 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 <filename>i386</filename> directory deals with PC hardware only, - while everything outside the <filename>i386</filename> directory is - common to all platforms which FreeBSD could potentially be ported - to.</para> - - <note> - <para>If there is <emphasis>not</emphasis> a - <filename>/usr/src/sys</filename> directory on your system, then the - kernel source has not been been installed. The easiest way to do this - is by running <command>/stand/sysinstall</command> as - <username>root</username>, choosing <literal>Configure</literal>, then - <literal>Distributions</literal>, then <literal>src</literal>, then - <literal>sys</literal>.</para> - </note> - - <para>Next, move to the <filename>i386/conf</filename> directory and copy - the <filename>GENERIC</filename> configuration file to the name you want - to give your kernel. For example:</para> - - <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput> -&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen> - - <para>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 - <filename>MYKERNEL</filename> for the purpose of this example.</para> - - <note> - <para>You must execute these and all of the following commands under the - root account or you will get <errortype>permission denied</errortype> - errors.</para> - </note> - - <para>Now, edit <filename>MYKERNEL</filename> with your favorite text - editor. If you are just starting out, the only editor available will - probably be <command>vi</command>, which is too complex to explain here, - but is covered well in many books in the <link - linkend="bibliography">bibliography</link>. However, FreeBSD does - offer an easier editor called “ee” which, if you are a - beginner, should be your editor of choice. Feel free to change the - comment lines at the top to reflect your configuration or the changes - you have made to differentiate it from - <filename>GENERIC</filename>.</para> - - <para>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 <filename>GENERIC</filename> configuration file might seem - overwhelming to you, so follow the descriptions in the <link - linkend="kernelconfig-config">Configuration File</link> section slowly - and carefully.</para> - - <note> - <para>If you are trying to upgrade your kernel from an older version of - FreeBSD, you will probably have to get a new version of - &man.config.8; from the same place you got the new kernel sources. - It is located in <filename>/usr/src/usr.sbin</filename>, so you will - need to download those sources as well. Re-build and install it - before running the next commands.</para> - </note> - - <para>When you are finished, type the following to compile and install - your kernel:</para> - - <screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput> -&prompt.root; <userinput>cd ../../compile/MYKERNEL</userinput> -&prompt.root; <userinput>make depend</userinput> -&prompt.root; <userinput>make</userinput> -&prompt.root; <userinput>make install</userinput></screen> - - <para>The new kernel will be copied to the root directory as - <filename>/kernel</filename> and the old kernel will be moved to - <filename>/kernel.old</filename>. Now, shutdown the system and reboot - to use your kernel. In case something goes wrong, there are some <link - linkend="kernelconfig-trouble">troubleshooting</link> instructions at - the end of this document. Be sure to read the section which explains how - to recover in case your new kernel <link - linkend="kernelconfig-noboot">does not boot</link>.</para> - - <note> - <para>If you have added any new devices (such as sound cards) you may - have to add some <link linkend="kernelconfig-nodes">device - nodes</link> to your <filename>/dev</filename> directory before you - can use them.</para> - </note> - </sect1> - - <sect1 id="kernelconfig-config"> - <title>The Configuration File</title> - - <para>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 - <literal>#</literal> is considered a comment and ignored. The following - sections describe each keyword, generally in the order they are listed - in <filename>GENERIC</filename>, although some related keywords have - been grouped together in a single section (such as Networking) even - though they are actually scattered throughout the - <filename>GENERIC</filename> file. - <anchor id="kernelconfig-options"> An exhaustive list of options and - more detailed explanations of the device lines is present in the - <filename>LINT</filename> configuration file, located in the same - directory as <filename>GENERIC</filename>. If you are in doubt as to - the purpose or necessity of a line, check first in - <filename>LINT</filename>.</para> - - <para>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 <option>-D</option> switch for the - <acronym>CFLAGS</acronym> line of the kernel Makefile. Naturally, this - caused a creeping optionism, with nobody really knowing which option has - been referenced in what files.</para> - - <para>In the new scheme, every <literal>#ifdef</literal> that is intended - to be dependent upon an option gets this option out of an - <filename>opt_<replaceable>foo</replaceable>.h</filename> declaration - file created in the compile directory by <command>config</command>. The - list of valid options for <command>config</command> lives in two files: - options that do not depend on the architecture are listed in - <filename>/sys/conf/options</filename>, architecture-dependent ones in - <filename>/sys/<replaceable>arch</replaceable>/conf/options.<replaceable>arch</replaceable></filename>, - with <emphasis>arch</emphasis> being for example - <filename>i386</filename>.</para> - - <important> - <title>Quoting numbers</title> - - <para>In all versions of FreeBSD up to and including 3-stable, - &man.config.8; required that any strings in the configuration file - that contained numbers used as text had to be enclosed in double - quotes.</para> - - <para>Where numbers are used as numbers, as in <literal>maxusers - 64</literal>, the quotation marks are <emphasis>not</emphasis> - required.</para> - - <para>This requirement was removed in FreeBSD-current (the 4.0 release - candidate).</para> - - <para>The examples here include the quote marks (<literal>"</literal>). - If you are building a kernel on a -current system you should omit - them.</para> - </important> - - <sect2> - <title>Mandatory Keywords</title> - - <para>These keywords are required in every kernel you build.</para> - - <variablelist> - <varlistentry> - <term><literal>machine <replaceable>arch</replaceable></literal> - </term> - - <listitem> - <para>The first keyword is <literal>machine</literal>, which, - since FreeBSD only runs on Intel 386 (and compatible) chips and - DEC Alpha processors, will be either - <replaceable>i386</replaceable> or - <replaceable>alpha</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>cpu - "<replaceable>cpu_type</replaceable>"</literal></term> - - <listitem> - <para>The next keyword is <literal>cpu</literal>, which includes - support for each CPU supported by FreeBSD. The possible values - of <replaceable>cpu_type</replaceable> for i386 systems - include:</para> - - <itemizedlist> - <listitem> - <para>I386_CPU</para> - </listitem> - - <listitem> - <para>I486_CPU</para> - </listitem> - - <listitem> - <para>I586_CPU</para> - </listitem> - - <listitem> - <para>I686_CPU</para> - </listitem> - </itemizedlist> - - <para>The values available for <replaceable>cpu_type</replaceable> - for Alpha systems include:</para> - - <itemizedlist> - <listitem> - <para>EV4</para> - </listitem> - - <listitem> - <para>EV5</para> - </listitem> - </itemizedlist> - - <para>Multiple instances of the <literal>cpu</literal> line may be - present with different values of - <replaceable>cpu_type</replaceable> as are present in the - <filename>GENERIC</filename> kernel. For a custom kernel, it is - best to specify only the cpu you have. If, for example, you - have an Intel Pentium, use <literal>I586_CPU</literal> for - <replaceable>cpu_type</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ident - <replaceable>machine_name</replaceable></literal></term> - - <listitem> - <para>Next, we have <literal>ident</literal>, which is the - identification of the kernel. You should change this from - <filename>GENERIC</filename> to whatever you named your kernel, in - this example, <filename>MYKERNEL</filename>. The value you put in - <literal>ident</literal> 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 - <literal>machine</literal> and <literal>cpu</literal>, enclose - your kernel's name in quotation marks if it contains any - numbers.</para> - - <para>Since this name is passed to the C compiler as a - <option>-D</option> switch, do not use names like - <filename>DEBUG</filename>, or something that could be confused - with another machine or CPU name, like - <literal>vax</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>maxusers - <replaceable>number</replaceable></literal></term> - - <listitem> - <para>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 - <literal>maxusers</literal> to at least <literal>4</literal>, - especially if you are using the X Window System or compiling - software. The reason is that the most important table set by - <literal>maxusers</literal> is the maximum number of processes, - which is set to <literal>20 + 16 * maxusers</literal>, so if you - set <literal>maxusers</literal> to <literal>1</literal>, 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 the X Window System. Even a - simple task like reading a man page will start up nine processes - to filter, decompress, and view it. Setting - <literal>maxusers</literal> to <literal>4</literal> will allow - you to have up to 84 simultaneous processes, which should be - enough for anyone. If, however, you see the dreaded - <errorname>proc table full</errorname> 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.</para> - - <note> - <para><literal>maxuser</literal> does <emphasis>not</emphasis> - 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 <emphasis>does</emphasis> limit - the number of simultaneous <emphasis>remote logins</emphasis> - is <link linkend="kernelconfig-ptys">pseudo-device pty - 16</link>.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>config - <replaceable>kernel_name</replaceable></literal> root on - <replaceable>root_device</replaceable></term> - - <listitem> - <para>This line specifies the location and name of the kernel. - Traditionally the kernel is called <filename>vmunix</filename> - but in FreeBSD, it is aptly named <filename>kernel</filename>. - You should always use <literal>kernel</literal> for - <replaceable>kernel_name</replaceable> 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 - <literal>wd0</literal> for systems with non-SCSI drives, or - <literal>da0</literal> for systems with SCSI drives.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>General Options</title> - - <para>These lines provide kernel support for various filesystems and - other options.</para> - - <variablelist> - <varlistentry> - <term><literal>options MATH_EMULATE</literal></term> - - <listitem> - <para>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.</para> - - <note> - <para>The normal math co-processor emulation routines that come - with FreeBSD are <emphasis>not</emphasis> 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 - <literal>GPL_MATH_EMULATE</literal> to use the superior GNU - math support, which is not included by default for licensing - reasons.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options "COMPAT_43"</literal></term> - - <listitem> - <para>Compatibility with 4.3BSD. Leave this in; some programs - will act strangely if you comment this out.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options BOUNCE_BUFFERS</literal></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options UCONSOLE</literal></term> - - <listitem> - <para>Allow users to grab the console, useful for X Windows. For - example, you can create a console xterm by typing <command>xterm - -C</command>, which will display any <command>write</command>, - <command>talk</command>, and other messages you receive, as well - as any console messages sent by the kernel.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options SYSVSHM</literal></term> - - <listitem> - <para>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 the X Window System, you will - definitely want to include this.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options SYSVSEM</literal></term> - - <listitem> - <para>Support for System V semaphores. Less commonly used but - only adds a few hundred bytes to the kernel.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options SYSVMSG</literal></term> - - <listitem> - <para>Support for System V messages. Again, only adds a few - hundred bytes to the kernel.</para> - - <note> - <para>The &man.ipcs.1; command will tell will list any processes - using each of these System V facilities.</para> - </note> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Filesystem Options</title> - - <para>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 <acronym>FFS</acronym> if you boot from a hard - drive, or <acronym>NFS</acronym> 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 Kernel Module directory - <filename>/modules</filename> the first time you mount a partition - of that type.</para> - - <variablelist> - <varlistentry> - <term><literal>options FFS</literal></term> - - <listitem> - <para>The basic hard drive filesystem; leave it in if you boot - from the hard disk.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options NFS</literal></term> - - <listitem> - <para>Network Filesystem. Unless you plan to mount partitions - from a Unix file server over Ethernet, you can comment this - out.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options MSDOSFS</literal></term> - - <listitem> - <para>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 - <application>mtools</application> 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).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options "CD9660"</literal></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options PROCFS</literal></term> - - <listitem> - <para>Process filesystem. This is a pretend filesystem mounted on - <filename>/proc</filename> which allows programs like &man.ps.1; - to give you more information on - what processes are running.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options MFS</literal></term> - - <listitem> - <para>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 <filename>/tmp</filename> - directory, since many programs store temporary data here. To - mount an MFS RAM disk on <filename>/tmp</filename>, add the - following line to <filename>/etc/fstab</filename> and then - reboot or type <command>mount /tmp</command>:</para> - - <programlisting> -/dev/wd1s2b /tmp mfs rw 0 0</programlisting> - - <note> - <para>Replace the <filename>/dev/wd1s2b</filename> with the name - of your swap partition, which will be listed in your - <filename>/etc/fstab</filename> as follows:</para> - - <programlisting> -/dev/wd1s2b none swap sw 0 0</programlisting> - </note> - - <note> - <para>Also, the <acronym>MFS</acronym> filesystem can - <emphasis>not</emphasis> be dynamically loaded, so you - <emphasis>must</emphasis> compile it into your kernel if you - want to experiment with it.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options "EXT2FS"</literal></term> - - <listitem> - <para>Linux's native file system. With ext2fs support you are - able to read and write to Linux partitions. This is useful if - you dual-boot FreeBSD and Linux and want to share data between - the two systems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options QUOTA</literal></term> - - <listitem> - <para>Enable disk quotas. If you have a public access system, and - do not want users to be able to overflow the - <filename>/home</filename> partition, you can establish disk - quotas for each user. Refer to the <link linkend="quotas">Disk - Quotas</link> section for more information.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Basic Controllers and Devices</title> - - <para>These sections describe the basic disk, tape, and CD-ROM - controllers supported by FreeBSD. There are separate sections for - <link linkend="kernelconfig-scsi">SCSI</link> controllers and <link - linkend="kernelconfig-network">network</link> cards.</para> - - <variablelist> - <varlistentry> - <term><literal>controller isa0</literal></term> - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller pci0</literal></term> - - <listitem> - <para>Include this if you have a PCI motherboard. This enables - auto-detection of PCI cards and gatewaying from the PCI to the - ISA bus.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller fdc0</literal></term> - - <listitem> - <para>Floppy drive controller: <literal>fd0</literal> is the - <devicename>A:</devicename> floppy drive, and - <literal>fd1</literal> is the <devicename>B:</devicename> drive. - <literal>ft0</literal> is a QIC-80 tape drive attached to the - floppy controller. Comment out any lines corresponding to - devices you do not have.</para> - - <note> - <para>QIC-80 tape support requires a separate filter program - called &man.ft.8;, see the manual page for - details.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller wdc0</literal></term> - - <listitem> - <para>This is the primary IDE controller. <literal>wd0</literal> - and <literal>wd1</literal> are the master and slave hard drive, - respectively. <literal>wdc1</literal> 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).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device wcd0<anchor - id="kernelconfig-atapi"></literal></term> - - <listitem> - <para>This device provides IDE CD-ROM support. Be sure to leave - <literal>wdc0</literal> uncommented, and <literal>wdc1</literal> - if you have more than one IDE controller and your CD-ROM is on - the second one card. To use this, you must also include the - line <literal>options ATAPI</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device npx0 at isa? port "IO_NPX" irq 13 - vector npxintr</literal></term> - - <listitem> - <para><literal>npx0</literal> is the interface to the floating - point math unit in FreeBSD, either the hardware co-processor or - the software math emulator. It is <emphasis>not</emphasis> - optional.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device wt0 at isa? port 0x300 bio irq 5 drq 1 vector - wtintr</literal></term> - - <listitem> - <para>Wangtek and Archive QIC-02/QIC-36 tape drive support</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Proprietary CD-ROM support</term> - - <listitem> - <para>The following drivers are for the so-called - <emphasis>proprietary</emphasis> CD-ROM drives. These drives - have their own controller card or might plug into a sound card - such as the SoundBlaster 16. They are <emphasis>not</emphasis> - IDE or SCSI. Most older single-speed and double-speed CD-ROMs - use these interfaces, while newer quad-speeds are likely to be - <link linkend="kernelconfig-atapi">IDE</link> or <link - linkend="kernelconfig-scsi">SCSI</link>.</para> - - <variablelist> - <varlistentry> - <term><literal>device mcd0 at isa? port 0x300 bio irq 10 - vector mcdintr</literal></term> - - <listitem> - <para>Mitsumi CD-ROM (LU002, LU005, FX001D).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device scd0 at isa? port 0x230 - bio</literal></term> - - <listitem> - <para>Sony CD-ROM (CDU31, CDU33A).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller matcd0 at isa? port ? - bio</literal></term> - - <listitem> - <para>Matsushita/Panasonic CD-ROM (sold by Creative Labs for - SoundBlaster).</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="kernelconfig-scsi"> - <title>SCSI Device Support</title> - - <para>This section describes the various SCSI controllers and devices - supported by FreeBSD.</para> - - <variablelist> - <varlistentry> - <term>SCSI Controllers</term> - - <listitem> - <para>The next ten or so lines include support for different kinds - of SCSI controllers. Comment out all except for the one(s) you - have:</para> - - <variablelist> - <varlistentry> - <term><literal>controller bt0 at isa? port "IO_BT0" bio irq ? - vector btintr</literal></term> - - <listitem> - <para>Most Buslogic controllers</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller uha0 at isa? port "IO_UHA0" bio irq - ? drq 5 vector uhaintr</literal></term> - - <listitem> - <para>UltraStor 14F and 34F</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller ahc0</literal></term> - - <listitem> - <para>Adaptec 274x/284x/294x</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller ahb0 at isa? bio irq ? - vector ahbintr</literal></term> - - <listitem> - <para>Adaptec 174x</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller aha0 at isa? port "IO_AHA0" bio - irq ? drq 5 vector ahaintr</literal></term> - - <listitem> - <para>Adaptec 154x</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller aic0 at isa? port - 0x340 bio irq 11 vector aicintr</literal></term> - - <listitem> - <para>Adaptec 152x and sound cards using Adaptec AIC-6360 - (slow!)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller nca0 at isa? port 0x1f88 bio irq - 10 vector ncaintr</literal></term> - - <listitem> - <para>ProAudioSpectrum cards using NCR 5380 or Trantor - T130</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller sea0 at isa? bio irq 5 iomem - 0xc8000 iosiz 0x2000 vector seaintr</literal></term> - - <listitem> - <para>Seagate ST01/02 8 bit controller (slow!)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller wds0 at isa? port 0x350 bio irq - 15 drq 6 vector wdsintr</literal></term> - - <listitem> - <para>Western Digital WD7000 controller</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller ncr0</literal></term> - - <listitem> - <para>NCR 53C810, 53C815, 53C825, 53C860, 53C875 PCI SCSI - controller</para> - - <note> - <para>This also supports the Diamond FirePort - controller.</para> - </note> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options SCSI_DELAY=15000</literal></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller scbus0</literal></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device da0</literal></term> - - <listitem> - <para>Support for SCSI hard drives.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device sa0</literal></term> - - <listitem> - <para>Support for SCSI tape drives.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device cd0</literal></term> - - <listitem> - <para>Support for SCSI CD-ROM drives.</para> - - <para>Note that the number <literal>0</literal> 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.</para> - - <para>If you want to “wire down” specific target IDs - to particular devices, refer to the appropriate section of the - <filename>LINT</filename> kernel config file.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Console, Bus Mouse, Keyboard, and X Server Support</title> - - <para>You must choose one of these two console types, and, if you plan - to use the X Window System with the vt220 console, enable the XSERVER - option and optionally, a bus mouse or PS/2 mouse device.</para> - - <variablelist> - <varlistentry> - <term><literal>device sc0 at isa? port "IO_KBD" tty irq 1 vector - scintr</literal></term> - - <listitem> - <para><literal>sc0</literal> is the default console driver, which - resembles an SCO console. Since most full-screen programs - access the console through a terminal database library like - <filename>termcap</filename>, it should not matter much whether - you use this or <literal>vt0</literal>, the VT220 compatible - console driver. When you log in, set your <envar>TERM</envar> - variable to “scoansi” if full-screen programs have - trouble running under this console.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>controller atkbdc0 at isa? port IO_KBD - tty</literal></term> - - <listitem> - <para>The keyboard controller <literal>atkbdc</literal> provides - I/O services for the AT keyboard and PS/2 style pointing - devices. This controller is required by the keyboard driver - <literal>atkbd</literal> and the PS/2 pointing device driver - <literal>psm</literal>. - </para> - - <variablelist> - <varlistentry> - <term><literal>options - "KBD_RESETDELAY=<replaceable>X</replaceable>", options - "KBD_MAXWAIT=<replaceable>Y</replaceable>"</literal></term> - - <listitem> - <para>The keyboard driver <literal>atkbd</literal> and the - pointing device driver <literal>psm</literal> may ask the - <literal>atkbdc</literal> driver to reset the devices - during the boot process. It sometimes takes a long time - before these devices respond to the reset command. These - options control how long the <literal>atkbdc</literal> - driver should wait before giving up — the driver - will wait <replaceable>X</replaceable> * - <replaceable>Y</replaceable> milliseconds at most. If the - drivers seem unable to detect devices, you may want to - increase these values. The default values are 200 - milliseconds for <replaceable>X</replaceable> and 5 for - <replaceable>Y</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options - "KBDIO_DEBUG=<replaceable>N</replaceable>"</literal></term> - - <listitem> - <para>Sets the debug level to <replaceable>N</replaceable>. - The default value is zero, which suppresses all debugging - output.</para> - </listitem> - </varlistentry> - </variablelist> - - <note> - <para>There can only be one <literal>atkbdc</literal> device - configured into the system. - </para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device atkbd0 at isa? tty irq 1</literal></term> - - <listitem> - <para>The <literal>atkbd</literal> driver, together with the - <literal>atkbdc</literal> controller, provides access to the - AT 84 keyboard or the AT enhanced keyboard which is connected - to the AT keyboard controller. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device vt0 at isa? port "IO_KBD" tty irq 1 vector - pcrint</literal></term> - - <listitem> - <para>This is a VT220-compatible console driver, backwards - compatible to VT100/102. It works well on some laptops which - have hardware incompatibilities with <literal>sc0</literal>. - Also, set your <envar>TERM</envar> variable to - <literal>vt100</literal> or <literal>vt220</literal> when you - log in. This driver might also prove useful when connecting to - a large number of different machines over the network, where the - <filename>termcap</filename> or <filename>terminfo</filename> - entries for the <devicename>sc0</devicename> device are often - not available — <literal>vt100</literal> should be - available on virtually any platform.</para> - - <variablelist> - <varlistentry> - <term><literal>options "PCVT_FREEBSD=210"</literal></term> - - <listitem> - <para>Required with the <literal>vt0</literal> console - driver.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options XSERVER</literal></term> - - <listitem> - <para>Only applicable with the <literal>vt0</literal> - console driver. This includes code required to run the - <application>XFree86</application> X Window Server under - the <literal>vt0</literal> console driver.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device mse0 at isa? port 0x23c tty irq 5 vector - ms</literal></term> - - <listitem> - <para>Use this device if you have a Logitech or ATI InPort bus - mouse card.</para> - - <note> - <para>If you have a serial mouse, ignore these two lines, and - instead, make sure the appropriate <link - linkend="kernelconfig-serial">serial</link> port is enabled - (probably COM1).</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device psm0 at isa? port "IO_KBD" conflicts tty irq - 12 vector psmintr</literal></term> - - <listitem> - <para>Use this device if your mouse plugs into the PS/2 mouse - port.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Serial and Parallel Ports</title> - - <para>Nearly all systems have these. If you are attaching a printer to - one of these ports, the <link linkend="printing">Printing</link> - section of the handbook is very useful. If you are using modem, <link - linkend="dialup">Dialup access</link> provides extensive detail on - serial port configuration for use with such devices.</para> - - <variablelist> - <varlistentry> - <term><literal>device sio0 at isa? port "IO_COM1" tty irq 4 vector - siointr</literal><anchor - id="kernelconfig-serial"></term> - - <listitem> - <para><literal>sio0</literal> through <literal>sio3</literal> 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 &man.sio.4; 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 - <literal>0x*2e8</literal>, 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.</para> - - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device lpt0 at isa? port? tty irq 7 vector - lptintr</literal></term> - - <listitem> - <para><literal>lpt0</literal> through <literal>lpt2</literal> 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.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="kernelconfig-network"> - <title>Networking</title> - - <para>FreeBSD, as with Unix in general, places a - <emphasis>big</emphasis> 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.</para> - - <variablelist> - <varlistentry> - <term><literal>options INET</literal></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Ethernet cards</term> - - <listitem> - <para>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):</para> - - <variablelist> - <varlistentry> - <term><literal>device cs0</literal></term> - - <listitem> - <para>IBM Etherjet and other Crystal Semi CS89x0-based - adapters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device de0</literal></term> - - <listitem> - <para>Ethernet adapters based on Digital Equipment DC21040, - DC21041 or DC21140 chips</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device fxp0</literal></term> - - <listitem> - <para>Intel EtherExpress Pro/100B</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device vx0</literal></term> - - <listitem> - <para>3Com 3C590 and 3C595 (buggy)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device cx0 at isa? port 0x240 net irq 15 drq 7 - vector cxintr</literal></term> - - <listitem> - <para>Cronyx/Sigma multiport sync/async (with Cisco or PPP - framing)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device ed0 at isa? port 0x280 net irq 5 iomem - 0xd8000 vector edintr</literal></term> - - <listitem> - <para>Western Digital and SMC 80xx and 8216; Novell NE1000 - and NE2000; 3Com 3C503; HP PC Lan Plus (HP27247B and - HP27252A)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device el0 at isa? port 0x300 net irq 9 vector - elintr</literal></term> - - <listitem> - <para>3Com 3C501 (slow!)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device eg0 at isa? port 0x310 net irq 5 vector - egintr</literal></term> - - <listitem> - <para>3Com 3C505</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device ep0 at isa? port 0x300 net irq 10 vector - epintr</literal></term> - - <listitem> - <para>3Com 3C509 (buggy)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device fe0 at isa? port 0x240 net irq ? vector - feintr</literal></term> - - <listitem> - <para>Fujitsu MB86960A/MB86965A Ethernet</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device fea0 at isa? net irq ? vector - feaintr</literal></term> - - <listitem> - <para>DEC DEFEA EISA FDDI adapter</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device ie0 at isa? port 0x360 net irq 7 iomem - 0xd0000 vector ieintr</literal></term> - - <listitem> - <para>AT&T StarLAN 10 and EN100; 3Com 3C507; unknown - NI5210; Intel EtherExpress 16</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device le0 at isa? port 0x300 net irq 5 iomem - 0xd0000 vector le_intr</literal></term> - - <listitem> - <para>Digital Equipment EtherWorks 2 and EtherWorks 3 - (DEPCA, DE100, DE101, DE200, DE201, DE202, DE203, DE204, - DE205, DE422)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device lnc0 at isa? port 0x300 net irq 10 drq 0 - vector lncintr</literal></term> - - <listitem> - <para>Lance/PCnet cards (Isolan, Novell NE2100, - NE32-VL)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device xl0</literal></term> - - <listitem> - <para>3Com Etherlink XL series PCI ethernet controllers - (3C905B and related).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device ze0 at isa? port 0x300 net irq 5 iomem - 0xd8000 vector zeintr</literal></term> - - <listitem> - <para>IBM/National Semiconductor PCMCIA ethernet - controller.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device zp0 at isa? port 0x300 net irq 10 iomem - 0xd8000 vector zpintr</literal></term> - - <listitem> - <para>3Com PCMCIA Etherlink III</para> - </listitem> - </varlistentry> - </variablelist> - - <note> - <para>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.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device loop</literal></term> - - <listitem> - <para><literal>loop</literal> is the generic loopback device for - TCP/IP. If you telnet or FTP to <hostid>localhost</hostid> - (a.k.a. <hostid role="ipaddr">127.0.0.1</hostid>) it will come - back at you through this pseudo-device. Mandatory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device ether</literal></term> - - <listitem> - <para><literal>ether</literal> is only needed if you have an - Ethernet card and includes generic Ethernet protocol - code.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device sl - <replaceable>number</replaceable></literal></term> - - <listitem> - <para><literal>sl</literal> 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 - <replaceable>number</replaceable> after <literal>sl</literal> - specifies how many simultaneous SLIP sessions to support. This - handbook has more information on setting up a SLIP <link - linkend="slipc">client</link> or <link - linkend="slips">server</link>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device ppp - <replaceable>number</replaceable></literal></term> - - <listitem> - <para><literal>ppp</literal> 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 <devicename>tun</devicename> and - offers more flexibility and features such as demand dialing. If - you still want to use this PPP driver, read the <link - linkend="ppp">kernel-mode PPP</link> section of the handbook. - As with the <literal>sl</literal> device, - <replaceable>number</replaceable> specifies how many - simultaneous PPP connections to support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device tun - <replaceable>number</replaceable></literal></term> - - <listitem> - <para><literal>tun</literal> 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 <literal>tun</literal> specifies the number of - simultaneous PPP sessions to support. See the <link - linkend="userppp">user-mode PPP</link> section of the handbook - for more information.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device bpfilter - <replaceable>number</replaceable></literal></term> - - <listitem> - <para>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 - &man.tcpdump.1; program. Note that implementation of this - capability can seriously compromise your overall network - security. The <replaceable>number</replaceable> 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.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Sound cards</title> - - <para>This is the first section containing lines that are not in the - <filename>GENERIC</filename> kernel. To include sound card support, you - will have to copy the appropriate lines from the LINT kernel (which - support for <emphasis>every</emphasis> device) as follows:</para> - - - <variablelist> - <varlistentry> - <term><literal>controller snd0</literal></term> - - <listitem> - <para>Generic sound driver code. Required for all of the - following sound cards except <literal>pca</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device pas0 at isa? port 0x388 irq 10 drq 6 vector - pasintr</literal></term> - - <listitem> - <para>ProAudioSpectrum digital audio and MIDI.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device sb0 at isa? port 0x220 irq 7 conflicts drq 1 - vector sbintr</literal></term> - - <listitem> - <para>SoundBlaster digital audio.</para> - - <note> - <para>If your SoundBlaster is on a different IRQ (such as 5), - change <literal>irq 7</literal> to, for example, <literal>irq - 5</literal> and remove the <literal>conflicts</literal> - keyword. </para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device sbxvi0 at isa? drq 5</literal></term> - - <listitem> - <para>SoundBlaster 16 digital 16-bit audio.</para> - - <note> - <para>If your SB16 is on a different 16-bit DMA channel (such as - 6 or 7), change the <literal>drq 5</literal> keyword - appropriately.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device sbmidi0 at isa? port 0x330</literal></term> - - <listitem> - <para>SoundBlaster 16 MIDI interface. If you have a SoundBlaster - 16, you must include this line, or the kernel will not - compile.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device gus0 at isa? port 0x220 irq 10 drq 1 vector - gusintr</literal></term> - - <listitem> - <para>Gravis Ultrasound.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device mss0 at isa? port 0x530 irq 10 drq 1 vector - adintr</literal></term> - - <listitem> - <para>Microsoft Sound System.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device opl0 at isa? port 0x388 - conflicts</literal></term> - - <listitem> - <para>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 <command>playmidi</command> - (in the ports collection).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device mpu0 at isa? port 0x330 irq 6 drq - 0</literal></term> - - <listitem> - <para>Roland MPU-401 stand-alone card.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device uart0 at isa? port 0x330 irq 5 vector - "m6850intr"</literal></term> - - <listitem> - <para>Stand-alone 6850 UART for MIDI.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device pca0 at isa? port "IO_TIMER1" - tty</literal><anchor id="kernelconfig-pcaudio"></term> - - <listitem> - <para>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).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>device pcm0 at isa? port ? tty irq 10 drq 1 flags 0x0 - </literal></term> - - <listitem> - <para>The <literal>pcm</literal> driver provides support for - various ISA sound cards that are compatible with the WSS/MSS - specs, or with the Sound Blaster Pro and Sound Blaster - 16.</para> - </listitem> - </varlistentry> - </variablelist> - - <note> - <para>There is some additional documentation in - <filename>/usr/src/sys/i386/isa/sound/</filename>. Also, if - you add any of these devices, be sure to create the sound <link - linkend="kernelconfig-nodes">device nodes</link>.</para> - </note> - </sect2> - - <sect2> - <title>Pseudo-devices</title> - - <para>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 <link linkend="kernelconfig-network">network-related</link> - pseudo-devices are in that section, while the remainder are - here.</para> - - <variablelist> - <varlistentry> - <term><literal>pseudo-device gzip</literal></term> - - <listitem> - <para><literal>gzip</literal> allows you to run FreeBSD programs - that have been compressed with <command>gzip</command>. The - programs in <filename>/stand</filename> are compressed so it is - a good idea to have this option in your kernel.</para> - - <note> - <para>The <literal>gzip</literal> feature currently only works - with a.out binaries.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device log</literal></term> - - <listitem> - <para><literal>log</literal> is used for logging of kernel error - messages. Mandatory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device pty - <replaceable>number</replaceable></literal><anchor - id="kernelconfig-ptys"></term> - - <listitem> - <para><literal>pty</literal> is a “pseudo-terminal” or - simulated login port. It is used by incoming - <command>telnet</command> and <command>rlogin</command> - sessions, xterm, and some other applications such as emacs. The - <replaceable>number</replaceable> indicates the number of - <literal>pty</literal>s to create. If you need more than - <filename>GENERIC</filename> default of 16 simultaneous xterm - windows and/or remote logins, be sure to increase this number - accordingly, up to a maximum of 256.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device snp - <replaceable>number</replaceable></literal></term> - - <listitem> - <para>Snoop device. This pseudo-device allows one terminal - session to watch another using the - &man.watch.8; command. Note that implementation of this - capability has important security and privacy implications. The - <replaceable>number</replaceable> after snp is the total number - of simultaneous snoop sessions. Optional.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device vn</literal></term> - - <listitem> - <para>Vnode driver. Allows a file to be treated as a device after - being set up with the &man.vnconfig.8; 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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device ccd - <replaceable>number</replaceable></literal></term> - - <listitem> - <para>Concatenated disks. This pseudo-device allows you to - concatenate multiple disk partitions into one large - “meta”-disk. The <replaceable>number</replaceable> - after ccd is the total number of concatenated disks (not total - number of disks that can be concatenated) that can be created. - (See &man.ccd.4; and &man.ccdconfig.8; man pages - for more details.) Optional.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Joystick, PC Speaker, Miscellaneous</title> - - <para>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 - <emphasis>every</emphasis> device):</para> - - <variablelist> - <varlistentry> - <term><literal>device joy0 at isa? port "IO_GAME"</literal></term> - - <listitem> - <para>PC joystick device.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>pseudo-device speaker</literal></term> - - <listitem> - <para>Supports IBM BASIC-style noises through the PC speaker. - Some fun programs which use this are - <filename>/usr/sbin/spkrtest</filename>, which is a shell script - that plays some simple songs, and - <filename>/usr/games/piano</filename> which lets you play songs - using the keyboard as a simple piano (this file only exists if - you have installed the <literal>games</literal> package). Also, - the excellent text role-playing game - <application>NetHack</application> (in the ports collection) can - be configured to use this device to play songs when you play - musical instruments in the game.</para> - - <para>See also the <link - linkend="kernelconfig-pcaudio">pca0</link> device.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="kernelconfig-nodes"> - <title>Making Device Nodes</title> - - <para>Almost every device in the kernel has a corresponding - “node” entry in the <filename>/dev</filename> 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 <filename>/dev/MAKEDEV</filename>, which is executed when you - first install the operating system, creates nearly all of the device - nodes supported. However, it does not create <emphasis>all</emphasis> - 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:</para> - - <para>Suppose you add the IDE CD-ROM support to the kernel. The line to - add is:</para> - - <programlisting> -controller wcd0</programlisting> - - <para>This means that you should look for some entries that start with - <filename>wcd0</filename> in the <filename>/dev</filename> directory, - possibly followed by a letter, such as <literal>c</literal>, or preceded - by the letter <literal>r</literal>, which means a “raw” - device. It turns out that those files are not there, so I must change - to the <filename>/dev</filename> directory and type:</para> - - <screen>&prompt.root; <userinput>sh MAKEDEV wcd0</userinput></screen> - - <para>When this script finishes, you will find that there are now - <filename>wcd0c</filename> and <filename>rwcd0c</filename> entries in - <filename>/dev</filename> so you know that it executed correctly.</para> - - <para>For sound cards, the command: - - <screen>&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen> - - creates the appropriate entries.</para> - - <note> - <para>When creating device nodes for devices such as sound cards, if - other people have access to your machine, it may be desirable to - protect the devices from outside access by adding them to the - <filename>/etc/fbtab</filename> file. See <command>man - fbtab</command> for more information.</para> - </note> - - <para>Follow this simple procedure for any other - non-<filename>GENERIC</filename> devices which do not have - entries.</para> - - <note> - <para>All SCSI controllers use the same set of <filename>/dev</filename> - entries, so you do not need to create these. Also, network cards and - SLIP/PPP pseudo-devices do not have entries in - <filename>/dev</filename> at all, so you do not have to worry about - these either.</para> - </note> - </sect1> - - <sect1 id="kernelconfig-trouble"> - <title>If Something Goes Wrong</title> - - <para>There are four categories of trouble that can occur when - building a custom kernel. They are:</para> - - <variablelist> - <varlistentry> - <term>Config command fails</term> - - <listitem> - <para>If the <command>config</command> command fails when you give - it your kernel description, you have probably made a simple error - somewhere. Fortunately, <command>config</command> will print the - line number that it had trouble with, so you can quickly skip to - it with <command>vi</command>. For example, if you see: - - <screen>config: line 17: syntax error</screen> - - you can skip to the problem in <command>vi</command> by typing - <command>17G</command> in command mode. Make sure the keyword is - typed correctly, by comparing it to the GENERIC kernel or another - reference.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Make command fails</term> - - <listitem> - <para>If the <command>make</command> command fails, it usually - signals an error in your kernel description, but not severe enough - for <command>config</command> 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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Kernel will not boot<anchor id="kernelconfig-noboot"></term> - - <listitem> - <para>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. - <filename>kernel.old</filename>) 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.</para> - - <para>After booting with a good kernel you can check over your - configuration file and try to build it again. One helpful - resource is the <filename>/var/log/messages</filename> file - which records, among other things, all of the kernel - messages from every successful boot. Also, the - &man.dmesg.8; command will print the kernel messages from the - current boot.</para> - - <note> - <para>If you are having trouble building a kernel, make sure to - keep a <filename>GENERIC</filename>, 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 - <filename>kernel.old</filename> because when installing a new - kernel, <filename>kernel.old</filename> is overwritten with the - last installed kernel which may be non-functional. Also, as - soon as possible, move the working kernel to the proper - <filename>kernel</filename> location or commands such as - &man.ps.1; will not work properly. The - proper command to “unlock” the kernel file that - <command>make</command> installs (in order to move another - kernel back permanently) is:</para> - - <screen>&prompt.root; <userinput>chflags noschg /kernel</userinput></screen> - - <para>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:</para> - - <screen>&prompt.root; <userinput>chflags schg /kernel</userinput></screen> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>Kernel works, but <command>ps</command> does not work any - more!</term> - - <listitem> - <para>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 “4.0” kernel on a - 3.1-RELEASE system, many system-status commands like &man.ps.1; - and &man.vmstat.8; will not work any more. You must recompile the - <filename>libkvm</filename> 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.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/kerneldebug/chapter.sgml b/en/handbook/kerneldebug/chapter.sgml deleted file mode 100644 index 7049bed32e..0000000000 --- a/en/handbook/kerneldebug/chapter.sgml +++ /dev/null @@ -1,597 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.16 1999-08-05 20:48:16 nik Exp $ ---> - -<chapter id="kerneldebug"> - <title>Kernel Debugging</title> - - <para><emphasis>Contributed by &a.paul; and &a.joerg;</emphasis></para> - - <sect1> - <title>Debugging a Kernel Crash Dump with <command>kgdb</command></title> - - <para>Here are some instructions for getting kernel debugging working on a - crash dump. They assume that you have enough swap space for a crash - dump. If you have multiple swap partitions and the first one is too - small to hold the dump, you can configure your kernel to use an - alternate dump device (in the <literal>config kernel</literal> line), or - you can specify an alternate using the - &man.dumpon.8; command. The best way to use &man.dumpon.8; is to set - the <literal>dumpdev</literal> variable in - <filename>/etc/rc.conf</filename>. Typically you want to specify one of - the swap devices specified in <filename>/etc/fstab</filename>. Dumps to - non-swap devices, tapes for example, are currently not supported. Config - your kernel using <command>config -g</command>. See <link - linkend="kernelconfig">Kernel Configuration</link> for details on - configuring the FreeBSD kernel.</para> - - <para>Use the &man.dumpon.8; command to tell the kernel where to dump to - (note that this will have to be done after configuring the partition in - question as swap space via &man.swapon.8;). This is normally arranged - via <filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>. - Alternatively, you can hard-code the dump device via the - <literal>dump</literal> clause in the <literal>config</literal> line of - your kernel config file. This is deprecated and should be used only if - you want a crash dump from a kernel that crashes during booting.</para> - - <note> - <para>In the following, the term <command>kgdb</command> refers to - <command>gdb</command> run in “kernel debug mode”. This - can be accomplished by either starting the <command>gdb</command> with - the option <option>-k</option>, or by linking and starting it under - the name <command>kgdb</command>. This is not being done by default, - however, and the idea is basically deprecated since the GNU folks do - not like their tools to behave differently when called by another - name. This feature may well be discontinued in further - releases.</para> - </note> - - <para>When the kernel has been built make a copy of it, say - <filename>kernel.debug</filename>, and then run <command>strip - -g</command> on the original. Install the original as normal. You - may also install the unstripped kernel, but symbol table lookup time for - some programs will drastically increase, and since the whole kernel is - loaded entirely at boot time and cannot be swapped out later, several - megabytes of physical memory will be wasted.</para> - - <para>If you are testing a new kernel, for example by typing the new - kernel's name at the boot prompt, but need to boot a different one in - order to get your system up and running again, boot it only into single - user state using the <option>-s</option> flag at the boot prompt, and - then perform the following steps:</para> - - <screen>&prompt.root; <userinput>fsck -p</userinput> -&prompt.root; <userinput>mount -a -t ufs</userinput> # so your file system for /var/crash is writable -&prompt.root; <userinput>savecore -N /kernel.panicked /var/crash</userinput> -&prompt.root; <userinput>exit</userinput> # ...to multi-user</screen> - - <para>This instructs &man.savecore.8; to use another kernel for symbol - name extraction. It would otherwise default to the currently running - kernel and most likely not do anything at all since the crash dump and - the kernel symbols differ.</para> - - <para>Now, after a crash dump, go to - <filename>/sys/compile/WHATEVER</filename> and run - <command>kgdb</command>. From <command>kgdb</command> do: - - <screen><userinput>symbol-file kernel.debug</userinput> -<userinput>exec-file /var/crash/kernel.0</userinput> -<userinput>core-file /var/crash/vmcore.0</userinput></screen> - - and voila, you can debug the crash dump using the kernel sources just - like you can for any other program.</para> - - <para>Here is a script log of a <command>kgdb</command> session - illustrating the procedure. Long lines have been folded to improve - readability, and the lines are numbered for reference. Despite this, it - is a real-world error trace taken during the development of the pcvt - console driver.</para> - -<screen> 1:Script started on Fri Dec 30 23:15:22 1994 - 2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput> - 3:&prompt.root; <userinput>kgdb kernel /var/crash/vmcore.1</userinput> - 4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel -...done. - 5:IdlePTD 1f3000 - 6:panic: because you said to! - 7:current pcb at 1e3f70 - 8:Reading in symbols for ../../i386/i386/machdep.c...done. - 9:<prompt>(kgdb)</prompt> <userinput>where</userinput> -10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767) -11:#1 0xf0115159 in panic () -12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698) -13:#3 0xf010185e in db_fncall () -14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073) -15:#5 0xf0101711 in db_command_loop () -16:#6 0xf01040a0 in db_trap () -17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723) -18:#8 0xf019d2eb in trap_fatal (...) -19:#9 0xf019ce60 in trap_pfault (...) -20:#10 0xf019cb2f in trap (...) -21:#11 0xf01932a1 in exception:calltrap () -22:#12 0xf0191503 in cnopen (...) -23:#13 0xf0132c34 in spec_open () -24:#14 0xf012d014 in vn_open () -25:#15 0xf012a183 in open () -26:#16 0xf019d4eb in syscall (...) -27:<prompt>(kgdb)</prompt> <userinput>up 10</userinput> -28:Reading in symbols for ../../i386/i386/trap.c...done. -29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\ -30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\ -31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\ -32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\ -33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\ -34:ss = -266427884}) (../../i386/i386/trap.c line 283) -35:283 (void) trap_pfault(&frame, FALSE); -36:<prompt>(kgdb)</prompt> <userinput>frame frame->tf_ebp frame->tf_eip</userinput> -37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done. -38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\ -39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403) -40:403 return ((*linesw[tp->t_line].l_open)(dev, tp)); -41:<prompt>(kgdb)</prompt> <userinput>list</userinput> -42:398 -43:399 tp->t_state |= TS_CARR_ON; -44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */ -45:401 -46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200) -47:403 return ((*linesw[tp->t_line].l_open)(dev, tp)); -48:404 #else -49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag)); -50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */ -51:407 } -52:<prompt>(kgdb)</prompt> <userinput>print tp</userinput> -53:Reading in symbols for ../../i386/i386/cons.c...done. -54:$1 = (struct tty *) 0x1bae -55:<prompt>(kgdb)</prompt> <userinput>print tp->t_line</userinput> -56:$2 = 1767990816 -57:<prompt>(kgdb)</prompt> <userinput>up</userinput> -58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\ -59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126) -60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p)); -61:<prompt>(kgdb)</prompt> <userinput>up</userinput> -62:#2 0xf0132c34 in spec_open () -63:<prompt>(kgdb)</prompt> <userinput>up</userinput> -64:#3 0xf012d014 in vn_open () -65:<prompt>(kgdb)</prompt> <userinput>up</userinput> -66:#4 0xf012a183 in open () -67:<prompt>(kgdb)</prompt> <userinput>up</userinput> -68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\ -69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\ -70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \ -71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \ -72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673) -73:673 error = (*callp->sy_call)(p, args, rval); -74:<prompt>(kgdb)</prompt> <userinput>up</userinput> -75:Initial frame selected; you cannot go up. -76:<prompt>(kgdb)</prompt> <userinput>quit</userinput> -77:&prompt.root; <userinput>exit</userinput> -78:exit -79: -80:Script done on Fri Dec 30 23:18:04 1994</screen> - <para>Comments to the above script:</para> - - <variablelist> - <varlistentry> - <term>line 6:</term> - - <listitem> - <para>This is a dump taken from within DDB (see below), hence the - panic comment “because you said to!”, and a rather - long stack trace; the initial reason for going into DDB has been a - page fault trap though.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 20:</term> - - <listitem> - <para>This is the location of function <function>trap()</function> - in the stack trace.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 36:</term> - - <listitem> - <para>Force usage of a new stack frame; this is no longer necessary - now. The stack frames are supposed to point to the right - locations now, even in case of a trap. (I do not have a new core - dump handy <g>, my kernel has not panicked for a rather long - time.) From looking at the code in source line 403, there is a - high probability that either the pointer access for - “tp” was messed up, or the array access was out of - bounds.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 52:</term> - - <listitem> - <para>The pointer looks suspicious, but happens to be a valid - address.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 56:</term> - - <listitem> - <para>However, it obviously points to garbage, so we have found our - error! (For those unfamiliar with that particular piece of code: - <literal>tp->t_line</literal> refers to the line discipline of - the console device here, which must be a rather small integer - number.)</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1> - <title>Debugging a crash dump with DDD</title> - - <para>Examining a kernel crash dump with a graphical debugger like - <command>ddd</command> is also possible. Add the <option>-k</option> - option to the <command>ddd</command> command line you would use - normally. For example;</para> - - <screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen> - - <para>You should then be able to go about looking at the crash dump using - <command>ddd</command>'s graphical interface.</para> - </sect1> - - <sect1> - <title>Post-mortem Analysis of a Dump</title> - - <para>What do you do if a kernel dumped core but you did not expect it, - and it is therefore not compiled using <command>config -g</command>? Not - everything is lost here. Do not panic!</para> - - <para>Of course, you still need to enable crash dumps. See above on the - options you have to specify in order to do this.</para> - - <para>Go to your kernel config directory - (<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>) - and edit your configuration file. Uncomment (or add, if it does not - exist) the following line</para> - - <programlisting> -makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols</programlisting> - - <para>Rebuild the kernel. Due to the time stamp change on the Makefile, - there will be some other object files rebuild, for example - <filename>trap.o</filename>. With a bit of luck, the added - <option>-g</option> option will not change anything for the generated - code, so you will finally get a new kernel with similar code to the - faulting one but some debugging symbols. You should at least verify the - old and new sizes with the &man.size.1; command. If there is a - mismatch, you probably need to give up here.</para> - - <para>Go and examine the dump as described above. The debugging symbols - might be incomplete for some places, as can be seen in the stack trace - in the example above where some functions are displayed without line - numbers and argument lists. If you need more debugging symbols, remove - the appropriate object files and repeat the <command>kgdb</command> - session until you know enough.</para> - - <para>All this is not guaranteed to work, but it will do it fine in most - cases.</para> - </sect1> - - <sect1> - <title>On-line Kernel Debugging Using DDB</title> - - <para>While <command>kgdb</command> as an offline debugger provides a very - high level of user interface, there are some things it cannot do. The - most important ones being breakpointing and single-stepping kernel - code.</para> - - <para>If you need to do low-level debugging on your kernel, there is an - on-line debugger available called DDB. It allows to setting - breakpoints, single-stepping kernel functions, examining and changing - kernel variables, etc. However, it cannot access kernel source files, - and only has access to the global and static symbols, not to the full - debug information like <command>kgdb</command>.</para> - - <para>To configure your kernel to include DDB, add the option line - - <programlisting> -options DDB</programlisting> - - to your config file, and rebuild. (See <link - linkend="kernelconfig">Kernel Configuration</link> for details on - configuring the FreeBSD kernel.</para> - - <note> - <para>Note that if you have an older version of the boot blocks, your - debugger symbols might not be loaded at all. Update the boot blocks; - the recent ones load the DDB symbols automagically.)</para> - </note> - - <para>Once your DDB kernel is running, there are several ways to enter - DDB. The first, and earliest way is to type the boot flag - <option>-d</option> right at the boot prompt. The kernel will start up - in debug mode and enter DDB prior to any device probing. Hence you can - even debug the device probe/attach functions.</para> - - <para>The second scenario is a hot-key on the keyboard, usually - Ctrl-Alt-ESC. For syscons, this can be remapped; some of the - distributed maps do this, so watch out. There is an option available - for serial consoles that allows the use of a serial line BREAK on the - console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal> - in the kernel config file). It is not the default since there are a lot - of crappy serial adapters around that gratuitously generate a BREAK - condition, for example when pulling the cable.</para> - - <para>The third way is that any panic condition will branch to DDB if the - kernel is configured to use it. For this reason, it is not wise to - configure a kernel with DDB for a machine running unattended.</para> - - <para>The DDB commands roughly resemble some <command>gdb</command> - commands. The first thing you probably need to do is to set a - breakpoint:</para> - - <screen><userinput>b function-name</userinput> -<userinput>b address</userinput></screen> - - <para>Numbers are taken hexadecimal by default, but to make them distinct - from symbol names; hexadecimal numbers starting with the letters - <literal>a-f</literal> need to be preceded with <literal>0x</literal> - (this is optional for other numbers). Simple expressions are allowed, - for example: <literal>function-name + 0x103</literal>.</para> - - <para>To continue the operation of an interrupted kernel, simply - type:</para> - - <screen><userinput>c</userinput></screen> - - <para>To get a stack trace, use:</para> - - <screen><userinput>trace</userinput></screen> - - <note> - <para>Note that when entering DDB via a hot-key, the kernel is currently - servicing an interrupt, so the stack trace might be not of much use - for you.</para> - </note> - - <para>If you want to remove a breakpoint, use</para> - - - <screen><userinput>del</userinput> -<userinput>del address-expression</userinput></screen> - - <para>The first form will be accepted immediately after a breakpoint hit, - and deletes the current breakpoint. The second form can remove any - breakpoint, but you need to specify the exact address; this can be - obtained from:</para> - - <screen><userinput>show b</userinput></screen> - - <para>To single-step the kernel, try:</para> - - <screen><userinput>s</userinput></screen> - - <para>This will step into functions, but you can make DDB trace them until - the matching return statement is reached by:</para> - - <screen><userinput>n</userinput></screen> - - <note> - <para>This is different from <command>gdb</command>'s - <command>next</command> statement; it is like <command>gdb</command>'s - <command>finish</command>.</para> - </note> - - <para>To examine data from memory, use (for example): - - <screen><userinput>x/wx 0xf0133fe0,40</userinput> -<userinput>x/hd db_symtab_space</userinput> -<userinput>x/bc termbuf,10</userinput> -<userinput>x/s stringbuf</userinput></screen> - - for word/halfword/byte access, and hexadecimal/decimal/character/ string - display. The number after the comma is the object count. To display - the next 0x10 items, simply use:</para> - - <screen><userinput>x ,10</userinput></screen> - - <para>Similarly, use - - <screen><userinput>x/ia foofunc,10</userinput></screen> - - to disassemble the first 0x10 instructions of - <function>foofunc</function>, and display them along with their offset - from the beginning of <function>foofunc</function>.</para> - - <para>To modify memory, use the write command:</para> - - <screen><userinput>w/b termbuf 0xa 0xb 0</userinput> -<userinput>w/w 0xf0010030 0 0</userinput></screen> - - <para>The command modifier - (<literal>b</literal>/<literal>h</literal>/<literal>w</literal>) - specifies the size of the data to be written, the first following - expression is the address to write to and the remainder is interpreted - as data to write to successive memory locations.</para> - - <para>If you need to know the current registers, use:</para> - - <screen><userinput>show reg</userinput></screen> - - <para>Alternatively, you can display a single register value by e.g. - - <screen><userinput>p $eax</userinput></screen> - - and modify it by:</para> - - <screen><userinput>set $eax new-value</userinput></screen> - - <para>Should you need to call some kernel functions from DDB, simply - say:</para> - - <screen><userinput>call func(arg1, arg2, ...)</userinput></screen> - - <para>The return value will be printed.</para> - - <para>For a &man.ps.1; style summary of all running processes, use:</para> - - <screen><userinput>ps</userinput></screen> - - <para>Now you have now examined why your kernel failed, and you wish to - reboot. Remember that, depending on the severity of previous - malfunctioning, not all parts of the kernel might still be working as - expected. Perform one of the following actions to shut down and reboot - your system:</para> - - <screen><userinput>call diediedie()</userinput></screen> - - <para>This will cause your kernel to dump core and reboot, so you can - later analyze the core on a higher level with kgdb. This command - usually must be followed by another <command>continue</command> - statement. There is now an alias for this: - <command>panic</command>.</para> - - <screen><userinput>call boot(0)</userinput></screen> - - <para>Which might be a good way to cleanly shut down the running system, - <function>sync()</function> all disks, and finally reboot. As long as - the disk and file system interfaces of the kernel are not damaged, this - might be a good way for an almost clean shutdown.</para> - - <screen><userinput>call cpu_reset()</userinput></screen> - - <para>is the final way out of disaster and almost the same as hitting the - Big Red Button.</para> - - <para>If you need a short command summary, simply type:</para> - - <screen><userinput>help</userinput></screen> - - <para>However, it is highly recommended to have a printed copy of the - &man.ddb.4; manual page ready for a debugging - session. Remember that it is hard to read the on-line manual while - single-stepping the kernel.</para> - </sect1> - - <sect1> - <title>On-line Kernel Debugging Using Remote GDB</title> - - <para>This feature has been supported since FreeBSD 2.2, and it is - actually a very neat one.</para> - - <para>GDB has already supported <emphasis>remote debugging</emphasis> for - a long time. This is done using a very simple protocol along a serial - line. Unlike the other methods described above, you will need two - machines for doing this. One is the host providing the debugging - environment, including all the sources, and a copy of the kernel binary - with all the symbols in it, and the other one is the target machine that - simply runs a similar copy of the very same kernel (but stripped of the - debugging information).</para> - - <para>You should configure the kernel in question with <command>config - -g</command>, include <option>DDB</option> into the configuration, and - compile it as usual. This gives a large blurb of a binary, due to the - debugging information. Copy this kernel to the target machine, strip - the debugging symbols off with <command>strip -x</command>, and boot it - using the <option>-d</option> boot option. Connect the first serial - line of the target machine to any serial line of the debugging host. - Now, on the debugging machine, go to the compile directory of the target - kernel, and start gdb:</para> - - <screen>&prompt.user; <userinput>gdb -k kernel</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.16 (i386-unknown-freebsd), -Copyright 1996 Free Software Foundation, Inc... -<prompt>(kgdb)</prompt> </screen> - - <para>Initialize the remote debugging session (assuming the first serial - port is being used) by:</para> - - <screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen> - - <para>Now, on the target host (the one that entered DDB right before even - starting the device probe), type:</para> - - <screen>Debugger("Boot flags requested debugger") -Stopped at Debugger+0x35: movb $0, edata+0x51bc -<prompt>db></prompt> <userinput>gdb</userinput></screen> - - <para>DDB will respond with:</para> - - <screen>Next trap will enter GDB remote protocol mode</screen> - - <para>Every time you type <command>gdb</command>, the mode will be toggled - between remote GDB and local DDB. In order to force a next trap - immediately, simply type <command>s</command> (step). Your hosting GDB - will now gain control over the target kernel:</para> - - <screen>Remote debugging using /dev/cuaa0 -Debugger (msg=0xf01b0383 "Boot flags requested debugger") - at ../../i386/i386/db_interface.c:257 -<prompt>(kgdb)</prompt></screen> - - <para>You can use this session almost as any other GDB session, including - full access to the source, running it in gud-mode inside an Emacs window - (which gives you an automatic source code display in another Emacs - window) etc.</para> - - <para>Remote GDB can also be used to debug LKMs. First build the LKM with - debugging symbols:</para> - - <screen>&prompt.root; <userinput>cd /usr/src/lkm/linux</userinput> -&prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen> - - <para>Then install this version of the module on the target machine, load - it and use <command>modstat</command> to find out where it was - loaded:</para> - - <screen>&prompt.root; <userinput>linux</userinput> -&prompt.root; <userinput>modstat</userinput> -Type Id Off Loadaddr Size Info Rev Module Name -EXEC 0 4 f5109000 001c f510f010 1 linux_mod</screen> - - <para>Take the load address of the module and add 0x20 (probably to - account for the a.out header). This is the address that the module code - was relocated to. Use the <command>add-symbol-file</command> command in - GDB to tell the debugger about the module:</para> - - <screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020</userinput> -add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at -text_addr = 0xf5109020? (y or n) <userinput>y</userinput> -<prompt>(kgdb)</prompt></screen> - - <para>You now have access to all the symbols in the LKM.</para> - </sect1> - - <sect1> - <title>Debugging a Console Driver</title> - - <para>Since you need a console driver to run DDB on, things are more - complicated if the console driver itself is failing. You might remember - the use of a serial console (either with modified boot blocks, or by - specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt), - and hook up a standard terminal onto your first serial port. DDB works - on any configured console driver, of course also on a serial - console.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/kernelopts/chapter.sgml b/en/handbook/kernelopts/chapter.sgml deleted file mode 100644 index ef95cd279c..0000000000 --- a/en/handbook/kernelopts/chapter.sgml +++ /dev/null @@ -1,164 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.9 1999-03-08 22:04:43 nik Exp $ ---> - -<chapter id="kernelopts"> - <title>Adding New Kernel Configuration Options</title> - - <para><emphasis>Contributed by &a.joerg;</emphasis></para> - - <note> - <para>You should be familiar with the section about <link - linkend="kernelconfig">kernel configuration</link> before reading - here.</para> - </note> - - <sect1> - <title>What's a <emphasis>Kernel Option</emphasis>, Anyway?</title> - - <para>The use of kernel options is basically described in the <link - linkend="kernelconfig-options">kernel configuration</link> section. - There's also an explanation of “historic” and - “new-style” options. The ultimate goal is to eventually - turn all the supported options in the kernel into new-style ones, so for - people who correctly did a <command>make depend</command> in their - kernel compile directory after running - &man.config.8;, the build process will automatically pick up modified - options, and only recompile those files where it is necessary. Wiping - out the old compile directory on each run of &man.config.8; as it is - still done now can then be eliminated again.</para> - - <para>Basically, a kernel option is nothing else than the definition of a - C preprocessor macro for the kernel compilation process. To make the - build truly optional, the corresponding part of the kernel source (or - kernel <filename>.h</filename> file) must be written with the option - concept in mind, i.e. the default must have been made overridable by the - config option. This is usually done with something like:</para> - - <programlisting> -#ifndef THIS_OPTION -#define THIS_OPTION (some_default_value) -#endif /* THIS_OPTION */</programlisting> - - <para>This way, an administrator mentioning another value for the option - in his config file will take the default out of effect, and replace it - with his new value. Clearly, the new value will be substituted into the - source code during the preprocessor run, so it must be a valid C - expression in whatever context the default value would have been - used.</para> - - <para>It is also possible to create value-less options that simply enable - or disable a particular piece of code by embracing it in</para> - - <programlisting> -#ifdef THAT_OPTION - -[your code here] - -#endif</programlisting> - - <para>Simply mentioning <literal>THAT_OPTION</literal> in the config file - (with or without any value) will then turn on the corresponding piece of - code.</para> - - <para>People familiar with the C language will immediately recognize that - everything could be counted as a “config option” where there - is at least a single <literal>#ifdef</literal> referencing it... - However, it's unlikely that many people would put</para> - - <programlisting> -options notyet,notdef</programlisting> - - <para>in their config file, and then wonder why the kernel compilation - falls over. <!-- smiley -->:-)</para> - - <para>Clearly, using arbitrary names for the options makes it very hard to - track their usage throughout the kernel source tree. That is the - rationale behind the <emphasis>new-style</emphasis> option scheme, where - each option goes into a separate <filename>.h</filename> file in the - kernel compile directory, which is by convention named - <filename>opt_<replaceable>foo</replaceable>.h</filename>. This way, - the usual Makefile dependencies could be applied, and - <command>make</command> can determine what needs to be recompiled once - an option has been changed.</para> - - <para>The old-style option mechanism still has one advantage for local - options or maybe experimental options that have a short anticipated - lifetime: since it is easy to add a new <literal>#ifdef</literal> to the - kernel source, this has already made it a kernel config option. In this - case, the administrator using such an option is responsible himself for - knowing about its implications (and maybe manually forcing the - recompilation of parts of his kernel). Once the transition of all - supported options has been done, &man.config.8; will warn whenever an - unsupported option appears in the config file, but it will nevertheless - include it into the kernel Makefile.</para> - </sect1> - - <sect1> - <title>Now What Do I Have to Do for it?</title> - - <para>First, edit <filename>sys/conf/options</filename> (or - <filename>sys/i386/conf/options.<replaceable><arch></replaceable></filename>, - e. g. <filename>sys/i386/conf/options.i386</filename>), and select an - <filename>opt_<replaceable>foo</replaceable>.h</filename> file where - your new option would best go into.</para> - - <para>If there is already something that comes close to the purpose of the - new option, pick this. For example, options modifying the overall - behaviour of the SCSI subsystem can go into - <filename>opt_scsi.h</filename>. By default, simply mentioning an - option in the appropriate option file, say <literal>FOO</literal>, - implies its value will go into the corresponding file - <filename>opt_foo.h</filename>. This can be overridden on the - right-hand side of a rule by specifying another filename.</para> - - <para>If there is no - <filename>opt_<replaceable>foo</replaceable>.h</filename> already - available for the intended new option, invent a new name. Make it - meaningful, and comment the new section in the - <filename>options[<replaceable>.<arch></replaceable>]</filename> - file. &man.config.8; will automagically pick up the change, and create - that file next time it is run. Most options should go in a header file - by themselves..</para> - - <para>Packing too many options into a single - <filename>opt_<replaceable>foo</replaceable>.h</filename> will cause too - many kernel files to be rebuilt when one of the options has been changed - in the config file.</para> - - <para>Finally, find out which kernel files depend on the new option. - Unless you have just invented your option, and it does not exist - anywhere yet, <screen>&prompt.user; <userinput>find /usr/src/sys -name - type f | xargs fgrep NEW_OPTION</userinput></screen> is your friend - in finding them. Go and edit all those files, and add <programlisting> - #include "opt_foo.h"</programlisting> <emphasis>on top</emphasis>, - before all the <literal>#include <xxx.h></literal> stuff. This - sequence is most important as the options could override defaults from - the regular include files, if the defaults are of the form - <programlisting> #ifndef NEW_OPTION #define NEW_OPTION (something) - #endif</programlisting> in the regular header.</para> - - <para>Adding an option that overrides something in a system header file - (i.e., a file sitting in <filename>/usr/include/sys/</filename>) is - almost always a mistake. - <filename>opt_<replaceable>foo</replaceable>.h</filename> cannot be - included into those files since it would break the headers more - seriously, but if it is not included, then places that include it may - get an inconsistent value for the option. Yes, there are precedents for - this right now, but that does not make them more correct.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/l10n/chapter.sgml b/en/handbook/l10n/chapter.sgml deleted file mode 100644 index 14e55a430c..0000000000 --- a/en/handbook/l10n/chapter.sgml +++ /dev/null @@ -1,333 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.11 1999-08-05 20:48:17 nik Exp $ ---> - -<chapter id="l10n"> - <title>Localization</title> - - <sect1 id="russian"> - <title>Russian Language (KOI8-R encoding)</title> - - <para><emphasis>Contributed by &a.ache; 1 May - 1997</emphasis>.</para> - - <para>See more info about KOI8-R encoding at <ulink - URL="http://www.nagual.pp.ru/~ache/koi8.html">KOI8-R References - (Russian Net Character Set)</ulink>.</para> - - <sect2 id="russian-console"> - <title>Console Setup</title> - - <procedure> - <step> - <para>Add following line to your kernel configuration file: - - <programlisting> -options "SC_MOUSE_CHAR=0x03"</programlisting> - - to move character codes used for mouse cursor off KOI8-R - pseudographics range.</para> - </step> - - <step> - <para>Russian console entry in - <filename>/etc/rc.conf</filename> should looks like:</para> - - <programlisting> -keymap=ru.koi8-r -keychange="61 ^[[K" -scrnmap=koi8-r2cp866 -font8x16=cp866b-8x16 -font8x14=cp866-8x14 -font8x8=cp866-8x8</programlisting> - - <note> - <para>^[ means that real ESC character must be entered into - <filename>/etc/rc.conf</filename>, not just ^[ string.</para> - </note> - - <para>This tuning means KOI8-R keyboard with Alternative screen font - mapped to KOI8-R encoding to preserve pseudographics, - <literal>Gray Delete</literal> key remapped to match Russian - &man.termcap.5; entry for - FreeBSD console.</para> - - <para>RUS/LAT switch will be <literal>CapsLock</literal>. Old - CapsLock function still available via - <literal>Shift+CapsLock</literal>. CapsLock LED will indicate RUS - mode, not CapsLock mode.</para> - </step> - - <step> - <para>For each <literal>ttyv?</literal> entry in - <filename>/etc/ttys</filename> change terminal type from - <literal>cons25</literal> to <literal>cons25r</literal>, i.e. each - entry should looks like:</para> - - <programlisting> -ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting> - </step> - </procedure> - </sect2> - - <sect2 id="russian-locale"> - <title>Locale Setup</title> - - <para><anchor id="russian-env"> There is two environment variables - for locale setup:</para> - - <itemizedlist> - <listitem> - <para><envar>LANG</envar> for POSIX &man.setlocale.3; family - functions;</para> - </listitem> - - <listitem> - <para><envar>MM_CHARSET</envar> for applications MIME character - set.</para> - </listitem> - </itemizedlist> - - <para>The best way is using <filename>/etc/login.conf</filename> - <literal>russian</literal> user's login class in - &man.passwd.5; entry login class position. See &man.login.conf.5; - for details.</para> - - <sect3 id="russian-class"> - <title>Login Class Method</title> - - <para>First of all check your <filename>/etc/login.conf</filename> - have <literal>russian</literal> login class, this entry may looks - like:</para> - - <programlisting> -russian:Russian Users Accounts:\ - :charset=KOI8-R:\ - :lang=ru_RU.KOI8-R:\ - :tc=default:</programlisting> - - <sect4> - <title>How to do it with &man.vipw.8;</title> - - <para>If you use &man.vipw.8; for adding new users, - <filename>/etc/master.passwd</filename> entry should looks - like:</para> - - <programlisting> -user:password:1111:11:russian:0:0:User Name:/home/user:/bin/csh</programlisting> - </sect4> - - <sect4> - <title>How to do it with &man.adduser.8;</title> - - <para>If you use &man.adduser.8; for adding new users:</para> - - <itemizedlist> - <listitem> - <para>Set - - <programlisting> -defaultclass = russian</programlisting> - - in <filename>/etc/adduser.conf</filename> (you must enter - <literal>default</literal> class for all non-Russian users in - this case);</para> - </listitem> - - <listitem> - <para>Alternative variant will be answering - <literal>russian</literal> each time when you see - - <screen><prompt>Enter login class:</prompt> default []:</screen> - prompt from &man.adduser.8;;</para> - </listitem> - - <listitem> - <para>Another variant: call - - <screen>&prompt.root; <userinput>adduser -class russian</userinput></screen> - - for each Russian user you want to add.</para> - </listitem> - </itemizedlist> - </sect4> - - <sect4> - <title>How to do it with &man.pw.8;</title> - - <para>If you use &man.pw.8; for adding new users, call it in this - form:</para> - - <screen>&prompt.root; <userinput>pw useradd user_name -L russian</userinput></screen> - </sect4> - </sect3> - - <sect3> - <title>Shell Startup Files Method</title> - - <para>If you don't want to use <link linkend="russian-class">login - class method</link> for some reasons, just set this <link - linkend="russian-env">two environment variables</link> in the - following shell startup files:</para> - - <itemizedlist> - <listitem> - <para><filename>/etc/profile</filename>:</para> - - <programlisting> -LANG=ru_RU.KOI8-R; export LANG -MM_CHARSET=KOI8-R; export MM_CHARSET</programlisting> - </listitem> - - <listitem> - <para><filename>/etc/csh.login</filename>:</para> - - <programlisting> -setenv LANG ru_RU.KOI8-R -setenv MM_CHARSET KOI8-R</programlisting> - </listitem> - </itemizedlist> - - <para>Alternatively you can add this instructions to</para> - - <itemizedlist> - <listitem> - <para><filename>/usr/share/skel/dot.profile</filename>:</para> - - <para>(similar to <filename>/etc/profile</filename> above);</para> - </listitem> - - <listitem> - <para><filename>/usr/share/skel/dot.login</filename>:</para> - - <para>(similar to <filename>/etc/csh.login</filename> - above).</para> - </listitem> - </itemizedlist> - </sect3> - </sect2> - - <sect2 id="russian-printer"> - <title>Printer Setup</title> - - <para>Since most printers with Russian characters comes with hardware - code page CP866, special output filter needed for KOI8-R -> CP866 - conversion. Such filter installed by default as - <filename>/usr/libexec/lpr/ru/koi2alt</filename>. So, Russian printer - <filename>/etc/printcap</filename> entry should looks like:</para> - - <programlisting> -lp|Russian local line printer:\ - :sh:of=/usr/libexec/lpr/ru/koi2alt:\ - :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting> - - <para>See &man.printcap.5; for detailed description.</para> - </sect2> - - <sect2 id="russian-msdosfs"> - <title>MSDOS FS and Russian file names</title> - - <para>Look at following example &man.fstab.5; entry to enable support - for Russian file names in MSDOS FS:</para> - - <programlisting> -/dev/sd0s1 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0</programlisting> - - <para>See &man.mount.msdos.8; for detailed description of - <option>-W</option> and <option>-L</option> options.</para> - </sect2> - - <sect2 id="russian-xwindow"> - <title>X Window Setup</title> - - <para>Step by step instructions:</para> - - <procedure> - <step> - <para>Do <link linkend="russian-locale">non-X locale setup</link> - first as described.</para> - - <note> - <para><anchor id="russian-note">Russian KOI8-R locale may not work - with old XFree86 releases (lower than 3.3). XFree86 port from - <filename>/usr/ports/x11/XFree86</filename> already have most - recent XFree86 version, so it will work, if you install XFree86 - from this port. XFree86 version shipped with the latest FreeBSD - distribution should work too (check XFree86 version number not - less than 3.3 first).</para> - </note> - </step> - - <step> - <para>Go to <filename>/usr/ports/russian/X.language</filename> - directory and say - - <screen>&prompt.root; <userinput>make all install</userinput></screen> - there. This port install latest version of KOI8-R fonts. XFree86 - 3.3 already have some KOI8-R fonts, but this ones scaled - better.</para> - - <para>Check find <literal>"Files"</literal> section in your - <filename>/etc/XF86Config</filename>, following lines must be - before any other <literal>FontPath</literal> entries:</para> - - <programlisting> -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc" -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi" -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"</programlisting> - - <para>If you use high resolution video mode, swap 75 dpi and 100 dpi - lines.</para> - </step> - - <step> - <para>To activate Russian keyboard add - - <programlisting> -XkbKeymap "xfree86(ru)"</programlisting> - - line into <literal>"Keyboard"</literal> section in your - <filename>/etc/XF86Config</filename>, also make sure that - <literal>XkbDisable</literal> is turned off (commented out) - there.</para> - - <para>RUS/LAT switch will be <literal>CapsLock</literal>. Old - CapsLock function still available via - <literal>Shift+CapsLock</literal> (in LAT mode only).</para> - - <note> - <para>Russian XKB keyboard may not work with old XFree86 versions, - see <link linkend="russian-note">locale note</link> for more - info. Russian XKB keyboard may not work with non-localized - applications too, minimally localized application should call - <literal>XtSetLanguageProc (NULL, NULL, NULL);</literal> - function early in the program.</para> - </note> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 id="german"> - <title>German Language (ISO 8859-1)</title> - - <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial - how to use umlauts on a FreeBSD machine. The tutorial is written in - German and available at <ulink - URL="http://www.de.FreeBSD.org/de/umlaute/">http://www.de.FreeBSD.org/de/umlaute/</ulink>.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/linuxemu/chapter.sgml b/en/handbook/linuxemu/chapter.sgml deleted file mode 100644 index d60b2c32f9..0000000000 --- a/en/handbook/linuxemu/chapter.sgml +++ /dev/null @@ -1,947 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.17 1999-08-05 20:48:18 nik Exp $ ---> - -<chapter id="linuxemu"> - <title>Linux Emulation</title> - - <para><emphasis>Contributed by &a.handy; and &a.rich;</emphasis></para> - - <sect1> - <title>How to Install the Linux Emulator</title> - - <para>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 2.1-STABLE branch is capable of running Linux - DOOM and Mathematica; the version present in &rel.current;-RELEASE is - vastly more capable and runs all these as well as Quake, Abuse, IDL, - netrek for Linux and a whole host of other programs.</para> - - <para>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 <filename>/proc</filename> filesystem (which is different - from the optional FreeBSD <filename>/proc</filename> filesystem) or - i386-specific calls, such as enabling virtual 8086 mode.</para> - - <para>Depending on which version of FreeBSD you are running, how you get - Linux-emulation up will vary slightly:</para> - - <sect2> - <title>Installing Linux Emulation in 2.1-STABLE</title> - - <para>The <filename>GENERIC</filename> kernel in 2.1-STABLE is not - configured for linux compatibility so 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).</para> - - <para>To enable the emulator, add the following to your configuration - file (c.f. <filename>/sys/i386/conf/LINT</filename>):</para> - - <programlisting> -options COMPAT_LINUX</programlisting> - - <para>If you want to run doom or other applications that need shared - memory, also add the following.</para> - - <programlisting> -options SYSVSHM</programlisting> - - <para>The linux system calls require 4.3BSD system call compatibility. - So make sure you have the following.</para> - - <programlisting> -options "COMPAT_43"</programlisting> - - <para>If you prefer to statically link the emulator in the kernel rather - than use the loadable kernel module (LKM), then add</para> - - <programlisting> -options LINUX</programlisting> - - <para>Then run config and install the new kernel as described in the - <link linkend="kernelconfig">kernel configuration</link> - section.</para> - - <para>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.</para> - - <screen>&prompt.root; <userinput>cd /usr/src/lkm/linux</userinput> -&prompt.root; <userinput>make all install</userinput></screen> - - <para>Once you have installed the kernel and the LKM, you can invoke - `linux' as root to load the LKM.</para> - - <screen>&prompt.root; <userinput>linux</userinput> -Linux emulator installed -Module loaded as ID 0</screen> - - <para>To see whether the LKM is loaded, run - <command>modstat</command>.</para> - - <screen>&prompt.user; modstat -Type Id Off Loadaddr Size Info Rev -Module Name EXEC 0 3 f0baf000 0018 f0bb4000 1 linux_emulator</screen> - - <para>You can cause the LKM to be loaded when the system boots in either - of two ways. In FreeBSD 2.2.1-RELEASE and 2.1-STABLE enable it in - <filename>/etc/sysconfig</filename> - - <programlisting> -linux=YES</programlisting> - - 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 - <filename>/etc/rc.local</filename> to add the following line.</para> - - <programlisting> -linux</programlisting> - </sect2> - - <sect2> - <title>Installing Linux Emulation in 2.2.2-RELEASE and later</title> - - <para>It is no longer necessary to specify <literal>options - LINUX</literal> or <literal>options COMPAT_LINUX</literal>. 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:</para> - - <orderedlist> - <listitem> - <para>In <filename>/etc/rc.conf</filename>, you need the following - line:</para> - - <programlisting> -linux_enable=YES</programlisting> - </listitem> - - <listitem> - <para>This, in turn, triggers the following action in - <filename>/etc/rc.i386</filename>:</para> - - <programlisting> -# Start the Linux binary emulation if requested. -if [ "X${linux_enable}" = X"YES" ]; then echo -n ' - linux'; linux > /dev/null 2>&1 -fi</programlisting> - </listitem> - </orderedlist> - - <para>If you want to verify it is running, modstat will do that:</para> - - <screen>&prompt.user; modstat -Type Id Off Loadaddr Size Info Rev Module Name -EXEC 0 4 f09e6000 001c f09ec010 1 linux_mod</screen> - - <para>However, there have been reports that this fails on some - 2.2-RELEASE and later systems. If for some reason you cannot load the - linux LKM, then statically link the emulator in the kernel by - adding - - <programlisting> -options LINUX</programlisting> - - to your kernel config file. Then run config and install the new - kernel as described in the <link linkend="kernelconfig">kernel - configuration</link> section.</para> - </sect2> - - <sect2> - <title>Installing Linux Runtime Libraries</title> - - <sect3> - <title>Installing using the linux_base port</title> - - <para>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_base port:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput> -&prompt.root; <userinput>make all install</userinput></screen> - - <para>and you should have a working linux emulator. Legend (and the - mail archives <!-- smiley -->:-) 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. Also, expect some programs to - complain about incorrect minor versions of the system libraries. In - general, however, this does not seem to be a problem.</para> - </sect3> - - <sect3> - <title>Installing libraries manually</title> - - <para>If you do not 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, - <filename>/compat/linux</filename>, 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, <filename>/lib/libc.so</filename>, FreeBSD will - first try to open <filename>/compat/linux/lib/libc.so</filename>, - and if that does not exist then it will try - <filename>/lib/libc.so</filename>. Shared libraries should be - installed in the shadow tree <filename>/compat/linux/lib</filename> - rather than the paths that the Linux <command>ld.so</command> - reports.</para> - - <para>FreeBSD-2.2-RELEASE and later works slightly differently with - respect to <filename>/compat/linux</filename>: all files, not just - libraries, are searched for from the “shadow root” - <filename>/compat/linux</filename>.</para> - - <para>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.</para> - </sect3> - - <sect3> - <title>How to install additional shared libraries</title> - - <para>What if you install the <filename>linux_base</filename> 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).</para> - - <para>If you have access to a Linux system, see what shared libraries - the application 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 <command>ldd - linuxxdoom</command>:</para> - - <screen>&prompt.user; <userinput>ldd linuxxdoom</userinput> -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</screen> - - <para>You would need to get all the files from the last column, and - put them under <filename>/compat/linux</filename>, with the names in - the first column as symbolic links pointing to them. This means you - eventually have these files on your FreeBSD system:</para> - - <screen>/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</screen> - - <note> - <para>Note that if you already have a Linux shared library with a - matching major revision number to the first column of the - <command>ldd</command> 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:</para> - - <screen>/compat/linux/lib/libc.so.4.6.27 -/compat/linux/lib/libc.so.4 -> libc.so.4.6.27</screen> - - <para>and you find a new binary that claims to require a later - version according to the output of <command>ldd</command>:</para> - - <screen>libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29</screen> - - <para>If it is only one or two versions out of date in the in the - trailing digit then do not worry about copying - <filename>/lib/libc.so.4.6.29</filename> too, because the program - should work fine with the slightly older version. However, if you - like you can decide to replace the <filename>libc.so</filename> - anyway, and that should leave you with:</para> - - <screen>/compat/linux/lib/libc.so.4.6.29 -/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen> - </note> - - <note> - <para>The symbolic link mechanism is <emphasis>only</emphasis> - needed for Linux binaries. The FreeBSD runtime linker takes care - of looking for matching major revision numbers itself and you do - not need to worry about it.</para> - </note> - </sect3> - - <sect3> - <title>Configuring the <filename>ld.so</filename> — for FreeBSD - 2.2-RELEASE and later</title> - - <para>This section applies only to FreeBSD 2.2-RELEASE and later. - Those running 2.1-STABLE should skip this section.</para> - - <para>Finally, if you run FreeBSD 2.2-RELEASE 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 - <filename>/compat/linux</filename> tree):</para> - - <screen>/compat/linux/lib/ld.so -/compat/linux/etc/ld.so.config</screen> - - <para>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.</para> - - <para>Retrieve the following files (all from the same ftp site to - avoid any version mismatches), and install them under - <filename>/compat/linux</filename> (i.e. - <filename>/foo/bar</filename> is installed as - <filename>/compat/linux/foo/bar</filename>):</para> - - <screen>/sbin/ldconfig -/usr/bin/ldd -/lib/libc.so.x.y.z -/lib/ld.so</screen> - - <para><command>ldconfig</command> and <command>ldd</command> do not - necessarily need to be under <filename>/compat/linux</filename>; 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 <filename>/usr/local/bin</filename> as - <command>ldconfig-linux</command> and - <command>ldd-linux</command>.</para> - - <para>Create the file - <filename>/compat/linux/etc/ld.so.conf</filename>, 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. <filename>/lib</filename> and <filename>/usr/lib</filename> - are standard, you could add the following:</para> - - <programlisting> -/usr/X11/lib -/usr/local/lib</programlisting> - - <para>When a linux binary opens a library such as - <filename>/lib/libc.so</filename> the emulator maps the name to - <filename>/compat/linux/lib/libc.so</filename> internally. All - linux libraries should be installed under /compat/linux (e.g. - <filename>/compat/linux/lib/libc.so</filename>, - <filename>/compat/linux/usr/X11/lib/libX11.so</filename>, etc.) in - order for the emulator to find them.</para> - - <para>Those running FreeBSD 2.2-RELEASE should run the Linux ldconfig - program.</para> - - <screen>&prompt.root <userinput>cd /compat/linux/lib</userinput> -&prompt.root; <userinput>/compat/linux/sbin/ldconfig</userinput></screen> - - <para><command>ldconfig</command> is statically linked, so it does not - need any shared libraries to run. It creates the file - <filename>/compat/linux/etc/ld.so.cache</filename> which contains - the names of all the shared libraries and should be rerun to - recreate this file whenever you install additional shared - libraries.</para> - - <para>On 2.1-STABLE do not install - <filename>/compat/linux/etc/ld.so.cache</filename> or run - <command>ldconfig</command>; in 2.1-STABLE the syscalls are - implemented differently and <command>ldconfig</command> is not - needed or used.</para> - - <para>You should now be set up for Linux binaries which only need a - shared libc. You can test this by running the Linux - <command>ldd</command> on itself. Supposing that you have it - installed as <command>ldd-linux</command>, it should produce - something like:</para> - - <screen>&prompt.root; <userinput>ldd-linux `which ldd-linux`</userinput> -libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29</screen> - - <para>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 <filename>/compat/linux</filename> tree. To do this, you run - the Linux version <command>ldd</command> on the new program, and - watch its output. <command>ldd</command> (see also the manual page - for &man.ldd.1;) will print a list of shared libraries - that the program depends on, in the form - <literal><replaceable>majorname</replaceable> - (<replaceable>jumpversion</replaceable>) => - <replaceable>fullname</replaceable></literal>.</para> - - <para>If it prints <literal>not found</literal> instead of - <replaceable>fullname</replaceable> it means that you need an extra - library. The library needed is shown in majorname and will be of - the form - <literal>lib<replaceable>XXXX</replaceable>.so.<replaceable>N</replaceable></literal>. - You will need to find a - <filename>lib<replaceable>XXXX</replaceable>.so.N.mm</filename> on a - Linux ftp site, and install it on your system. The - <replaceable>XXXX</replaceable> (name) and - <replaceable>N</replaceable> (major revision number) should match; - the minor number(s) <replaceable>mm</replaceable> are less - important, though it is advised to take the most recent - version.</para> - </sect3> - </sect2> - - <sect2> - <title>Installing Linux ELF binaries</title> - - <para>ELF binaries sometimes require an extra step of - “branding”. If you attempt to run an unbranded ELF - binary, you will get an error message like the following;</para> - - <screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput> -ELF binary type not known -Abort</screen> - - <para>To help the FreeBSD kernel distinguish between a FreeBSD ELF - binary from a Linux binary, use the &man.brandelf.1; utility.</para> - - <screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen> - - <para>The GNU toolchain now places the appropriate branding information - into ELF binaries automatically, so you should be needing to do this - step increasingly rarely in future.</para> - </sect2> - - <sect2> - <title>Configuring the host name resolver</title> - - <para>If DNS does not work or you get the messages - - <screen>resolv+: "bind" is an invalid keyword resolv+: -"hosts" is an invalid keyword</screen> - - then you need to configure a - <filename>/compat/linux/etc/host.conf</filename> file containing: - - <programlisting> -order hosts, bind -multi on</programlisting> - - where the order here specifies that <filename>/etc/hosts</filename> is - searched first and DNS is searched second. When - <filename>/compat/linux/etc/host.conf</filename> is not installed - linux applications find FreeBSD's <filename>/etc/host.conf</filename> - and complain about the incompatible FreeBSD syntax. You should remove - <literal>bind</literal> if you have not configured a name-server using - the <filename>/etc/resolv.conf</filename> file.</para> - - <para>Lastly, those who run 2.1-STABLE need to set an the - <envar>RESOLV_HOST_CONF</envar> environment variable so that - applications will know how to search the host tables. If you run - FreeBSD 2.2-RELEASE or later, you can skip this. For the - <filename>/bin/csh</filename> shell use:</para> - - <screen>&prompt.user; <userinput>setenv RESOLV_HOST_CONF /compat/linux/etc/host.conf</userinput></screen> - - <para>For <filename>/bin/sh</filename> use:</para> - - <screen>&prompt.user; <userinput>RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF</userinput></screen> - </sect2> - - <sect2> - <title>Finding the necessary files</title> - - <note> - <para>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.</para> - </note> - - <para>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:</para> - - <orderedlist> - <listitem> - <para>sunsite.unc.edu:/pub/Linux/distributions</para> - </listitem> - - <listitem> - <para>tsx-11.mit.edu:/pub/linux/distributions</para> - </listitem> - </orderedlist> - - <para>Some European mirrors:</para> - - <orderedlist> - <listitem> - <para>ftp.luth.se:/pub/linux/distributions</para> - </listitem> - - <listitem> - <para>ftp.demon.co.uk:/pub/unix/linux</para> - </listitem> - - <listitem> - <para>src.doc.ic.ac.uk:/packages/linux/distributions</para> - </listitem> - </orderedlist> - - <para>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 <filename>contents</filename> - 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:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Library</entry> - <entry>Package</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>ld.so</filename></entry> - <entry>ldso</entry> - </row> - - <row> - <entry><filename>ldconfig</filename></entry> - <entry>ldso</entry> - </row> - - <row> - <entry><filename>ldd</filename></entry> - <entry>ldso</entry> - </row> - - <row> - <entry><filename>libc.so.4</filename></entry> - <entry>shlibs</entry> - </row> - - <row> - <entry><filename>libX11.so.6.0</filename></entry> - <entry>xf_lib</entry> - </row> - - <row> - <entry><filename>libXt.so.6.0</filename></entry> - <entry>xf_lib</entry> - </row> - - <row> - <entry><filename>libX11.so.3</filename></entry> - <entry>oldlibs</entry> - </row> - - <row> - <entry><filename>libXt.so.3</filename></entry> - <entry>oldlibs</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>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 <literal>PACKAGE LOCATION</literal>, 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:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead - <row> - <entry>Package</entry> - <entry>Location</entry> - </row> - </thead> - - <tbody> - <row> - <entry>ldso</entry> - <entry>diska2</entry> - </row> - - <row> - <entry>shlibs</entry> - <entry>diska2</entry> - </row> - - <row> - <entry>oldlibs</entry> - <entry>diskx6</entry> - </row> - - <row> - <entry>xf_lib</entry> - <entry>diskx9</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>The locations called - “disk<replaceable>XX</replaceable>” refer to the - <filename>slakware/<replaceable>XX</replaceable></filename> - subdirectories of the distribution, others may be found in the - <filename>contrib</filename> 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):</para> - - <itemizedlist> - <listitem> - <para><filename>slakware/a2/ldso.tgz</filename></para> - </listitem> - - <listitem> - <para><filename>slakware/a2/shlibs.tgz</filename></para> - </listitem> - - <listitem> - <para><filename>slakware/x6/oldlibs.tgz</filename></para> - </listitem> - - <listitem> - <para><filename>slakware/x9/xf_lib.tgz</filename></para> - </listitem> - </itemizedlist> - - <para>Extract the files from these gzipped tarfiles in your - <filename>/compat/linux</filename> directory (possibly omitting or - afterwards removing files you do not need), and you are done.</para> - - <para><emphasis>See also:</emphasis> - <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/2.0.5-RELEASE/xperimnt/linux-emu/README</filename> and <filename>/usr/src/sys/i386/ibcs2/README.iBCS2</filename></para> - </sect2> - </sect1> - - <sect1 id="mathematica"> - <title>How to Install Mathematica on FreeBSD</title> - - <para><emphasis>Contributed by &a.rich; and &a.chuck;</emphasis></para> - - <para>This document shows how to install the Linux binary distribution of - Mathematica 2.2 on FreeBSD 2.1.</para> - - <para>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.</para> - - <para>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.</para> - - <sect2> - <title>Unpacking the Mathematica distribution</title> - - <para>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 <filename>LINUX.TAR</filename>. You can, for example, - unpack this into <filename>/usr/local/Mathematica</filename>:</para> - - <screen>&prompt.root; <userinput>cd /usr/local</userinput> -&prompt.root; <userinput>mkdir Mathematica</userinput> -&prompt.root; <userinput>cd Mathematica</userinput> -&prompt.root; <userinput>tar -xvf /cdrom/LINUX.TAR</userinput></screen> - </sect2> - - <sect2> - <title>Obtaining your Mathematica Password</title> - - <para>Before you can run Mathematica you will have to obtain a password - from Wolfram that corresponds to your “machine ID”.</para> - - <para>Once you have installed the linux compatibility runtime libraries - and unpacked the mathematica you can obtain the “machine - ID” by running the program <command>mathinfo</command> in the - Install directory.</para> - - <screen>&prompt.root; <userinput>cd /usr/local/Mathematica/Install</userinput> -&prompt.root; <userinput>mathinfo</userinput> -LINUX: 'ioctl' fd=5, typ=0x89(), num=0x27 not implemented -richc.isdn.bcm.tmc.edu 9845-03452-90255</screen> - - <para>So, for example, the “machine ID” of - <hostid>richc</hostid> is <literal>9845-03452-90255</literal>. You - can ignore the message about the ioctl that is not implemented. It - will not prevent Mathematica from running in any way and you can - safely ignore it, though you will see the message every time you run - Mathematica.</para> - - <para>When you register with Wolfram, either by email, phone or fax, you - will 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.</para> - - <para>You can do this by invoking:</para> - - <screen>&prompt.root; <userinput>cd /usr/local/Mathematica/Install</userinput> -&prompt.root; <userinput>math.install</userinput></screen> - - <para>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 is OK; you can simply edit the file - <filename>mathpass</filename> in this same directory to correct the - info manually.</para> - - <para>After getting past the password, math.install will ask you if you - accept the install defaults provided, 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 will not - 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 <command>math.install</command> program. The - directories we chose to create beforehand and specify to - <command>math.install</command> were:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry><filename>/usr/local/Mathematica/bin</filename></entry> - <entry>for binaries</entry> - </row> - - <row> - <entry><filename>/usr/local/Mathematica/man/man1</filename></entry> - <entry>for man pages</entry> - </row> - - <row> - <entry>/usr/local/Mathematica/lib/X11</entry> - <entry>for the XKeysymb file</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>You can also tell it to use <filename>/tmp/math.record</filename> - for the system record file, where it puts logs of sessions. After - this <command>math.install</command> will continue on to unpacking - things and placing everything where it should go.</para> - - <para>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 - <filename>/usr/local/Mathematica/FrontEnd</filename> directory and - execute the <command>xfe.install</command> shell script. You will - have to tell it where to put things, but you do not have to create any - directories because it will use the same directories that had been - created for math.install. When it finishes, there should be a new - shell script in <filename>/usr/local/Mathematica/bin</filename> called - <filename>mathematica</filename>.</para> - - <para>Lastly, you need to modify each of the shell scripts that - Mathematica has installed. At the beginning of every shell script in - <filename>/usr/local/Mathematica/bin</filename> add the following - line:</para> - - <screen>&prompt.user; <userinput>XKEYSYMDB=/usr/local/Mathematica/lib/X11/XKeysymDB; export XKEYSYMDB</userinput></screen> - - <para>This tells Mathematica were to find its own - version of the key mapping file <filename>XKeysymDB</filename>. - Without this you will get pages of error messages about missing - key mappings.</para> - - <para>On 2.1-STABLE you need to add the following as well:</para> - - <screen>&prompt.user; <userinput>RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF</userinput></screen> - - <para>This tells Mathematica to use the linux version of host.conf. - This file has a different syntax from FreeBSD's host.conf, so you will - get an error message about <filename>/etc/host.conf</filename> if you - leave this out.</para> - - <para>You might also want to modify your - <filename>/etc/manpath.config</filename> file to read the new man - directory, and you may need to edit your <filename>~/.cshrc</filename> - file to add <filename>/usr/local/Mathematica/bin</filename> to your - path.</para> - - <para>That is about all it takes. With this you should be able to type - <command>mathematica</command> and get a really slick looking - Mathematica Notebook screen up. Mathematica has included the Motif - user interfaces, but it is compiled in statically, so you do not need - the Motif libraries. Good luck doing this yourself!</para> - </sect2> - - <sect2> - <title>Bugs</title> - - <para>The Notebook front end is known to hang sometimes when reading - notebook files with an error messages similar to:</para> - - <screen><errorname>File .../Untitled-1.mb appears to be broken for OMPR.257.0</errorname></screen> - - <para>We have not found the cause for this, but it only affects the - Notebook's X Window front end, not the mathematica engine itself. So - the command line interface invoked by 'math' is unaffected by this - bug.</para> - </sect2> - - <sect2> - <title>Acknowledgments</title> - - <para>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! <!-- smiley -->:-)</para> - </sect2> - </sect1> - - <sect1> - <title>How does the emulation work?</title> - - <para>This section is based heavily on an e-mail written to the - <email>chat@FreeBSD.org</email> mailing list, written by Terry Lambert - <email>tlambert@primenet.com</email> (Message ID: - <literal><199906020108.SAA07001@usr09.primenet.com></literal>).</para> - - <para>FreeBSD has an abstraction called an “execution class - loader”. This is a wedge into the &man.execve.2; system - call.</para> - - <para>What happens is that FreeBSD has a list of loaders, instead of a - single loader with a fallback to the <literal>#!</literal> loader for - running any shell interpreters or shell scripts.</para> - - <para>Historically, the only loader on the UNIX platform examined the - magic number (generally the first 4 or 8 bytes of the file) to see if it - was a binary known to the system, and if so, invoked the binary - loader.</para> - - <para>If it was not the binary type for the system, the &man.execve.2; - call returned a failure, and the shell attempted to start executing it - as shell commands.</para> - - <para>The assumption was a default of “whatever the current shell - is”.</para> - - <para>Later, a hack was made for &man.sh.1; to examine the first two - characters, and if they were <literal>:\n</literal>, then it invoked the - &man.csh.1; shell instead (I believe SCO first made this hack, but am - willing to be corrected).</para> - - <para>What FreeBSD does now is go through a list of loaders, with a - generic <literal>#!</literal> loader that knows about interpreters as - the characters which follow to the next whitespace next to last, - followed by a fallback to <filename>/bin/sh</filename>.</para> - - <para>For the Linux binary emulation, FreeBSD sees the magic number as an - ELF binary (it makes no distinction between FreeBSD, Solaris, Linux, or - any other OS which has an ELF image type, at this point).</para> - - <para>The ELF loader looks for a specialized <emphasis>brand</emphasis>, - which is a comment section in the ELF image, and which is not present on - SVR4/Solaris ELF binaries.</para> - - <para>For Linux binaries to function, they must be - <emphasis>branded</emphasis> as type <literal>Linux</literal>; from - &man.brandelf.1;:</para> - - <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen> - - <para>When this is done, the ELF loader will see the - <literal>Linux</literal> brand on the file.</para> - - <para>When the ELF loader sees the <literal>Linux</literal> brand, the - loader replaces a pointer in the <literal>proc</literal> - structure. All system calls are indexed through this pointer (in a - traditional UNIX system, this would be the <literal>sysent[]</literal> structure array, containing the system - calls). In addition, the process is flagged for special handling of the - trap vector for the signal trampoline code, and sever other (minor) - fixups that are handled by the Linux kernel module.</para> - - <para>The Linux system call vector contains, among other things, a list of - <literal>sysent[]</literal> entries whose addresses reside in the kernel - module.</para> - - <para>When a system call is called by the Linux binary, the trap code - dereferences the system call function pointer off the - <literal>proc</literal> structure, and gets the Linux, not the FreeBSD, - system call entry points.</para> - - <para>In addition, the Linux emulation dynamically - <emphasis>reroots</emphasis> lookups; this is, in effect, what the - <literal>union</literal> option to FS mounts ( <emphasis>not</emphasis> - the unionfs!) does. First, an attempt is made to lookup the file in the - <filename>/compat/linux/<replaceable>original-path</replaceable></filename> - directory, <emphasis>then</emphasis> only if that fails, the lookup is - done in the - <filename>/<replaceable>original-path</replaceable></filename> - directory. This makes sure that binaries that require other binaries - can run (e.g., the Linux toolchain can all run under emulation). It - also means that the Linux binaries can load and exec FreeBSD binaries, - if there are no corresponding Linux binaries present, and that you could - place a &man.uname.1; command in the <filename>/compat/linux</filename> - directory tree to ensure that the Linux binaries could not tell they - were not running on Linux.</para> - - <para>In effect, there is a Linux kernel in the FreeBSD kernel; the - various underlying functions that implement all of the services provided - by the kernel are identical to both the FreeBSD system call table - entries, and the Linux system call table entries: file system - operations, virtual memory operations, signal delivery, System V IPC, - etc… The only difference is that FreeBSD binaries get the FreeBSD - <emphasis>glue</emphasis> functions, and Linux binaries get the Linux - <emphasis>glue</emphasis> functions (most older OS's only had their own - <emphasis>glue</emphasis> functions: addresses of functions in a static - global <literal>sysent[]</literal> structure array, instead of addresses - of functions dereferenced off a dynamically initialized pointer in the - <literal>proc</literal> structure of the process making the - call).</para> - - <para>Which one is the native FreeBSD ABI? It does not matter. Basically - the only difference is that (currently; this could easily be changed in - a future release, and probably will be after this) the FreeBSD - <emphasis>glue</emphasis> functions are statically linked into the - kernel, and the Linux glue functions can be statically linked, or they - can be accessed via a kernel module.</para> - - <para>Yeah, but is this really emulation? No. It is an ABI - implementation, not an emulation. There is no emulator (or simulator, - to cut off the next question) involved.</para> - - <para>So why is it called “Linux emulation”? To make it hard - to sell FreeBSD! <!-- smiley -->8-). Really, it is because the - historical implementation was done at a time when there was really no - word other than that to describe what was going on; saying that FreeBSD - ran Linux binaries was not true, if you did not compile the code in or - load a module, and there needed to be a word to describe what was being - loaded—hence “the Linux emulator”.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/mail/chapter.sgml b/en/handbook/mail/chapter.sgml deleted file mode 100644 index 5c53005371..0000000000 --- a/en/handbook/mail/chapter.sgml +++ /dev/null @@ -1,567 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.11 1999-08-05 20:48:18 nik Exp $ ---> - -<chapter id="mail"> - <title>Electronic Mail</title> - - <para><emphasis>Contributed by &a.wlloyd;.</emphasis></para> - - <para>Electronic Mail configuration is the subject of many <link - linkend="bibliography">System Administration</link> books. If you plan - on doing anything beyond setting up one mailhost for your network, you - need industrial strength help.</para> - - <para>Some parts of E-Mail configuration are controlled in the Domain Name - System (DNS). If you are going to run your own own DNS server check out - <filename>/etc/namedb</filename> and <command>man -k named</command> for - more information.</para> - - <sect1> - <title>Basic Information</title> - - <para>These are the major programs involved in an E-Mail exchange. A - “mailhost” is a server that is responsible for delivering - and receiving all email for your host, and possibly your network.</para> - - <sect2> - <title>User program</title> - - <para>This is a program like <application >elm</application>, - <application>pine</application>, <application>mail</application>, or - something more sophisticated like a WWW browser. This program will - simply pass off all e-mail transactions to the local - “mailhost” , either by calling <command>sendmail</command> - or delivering it over TCP.</para> - </sect2> - - <sect2> - <title>Mailhost Server Daemon</title> - - <para>Usually this program is <command>sendmail</command> or - <command>smail</command> running in the background. Turn it off or - change the command line options in <filename>/etc/rc.conf</filename> - (or, prior to FreeBSD 2.2.2, <filename>/etc/sysconfig</filename>). It - is best to leave it on, unless you have a specific reason to want it - off. Example: You are building a <link - linkend="firewalls">Firewall</link>.</para> - - <para>You should be aware that <command>sendmail</command> is a - potential weak link in a secure site. Some versions of - <command>sendmail</command> have known security problems.</para> - - <para><command>sendmail</command> does two jobs. It looks after - delivering and receiving mail.</para> - - <para>If <command>sendmail</command> needs to deliver mail off your site - it will look up in the DNS to determine the actual host that will - receive mail for the destination.</para> - - <para>If it is acting as a delivery agent <command>sendmail</command> - will take the message from the local queue and deliver it across the - Internet to another sendmail on the receivers computer.</para> - </sect2> - - <sect2> - <title>DNS — Name Service</title> - - <para>The Domain Name System and its daemon <command>named</command>, - contain the database mapping hostname to IP address, and hostname to - mailhost. The IP address is specified in an A record. The MX record - specifies the mailhost that will receive mail for you. If you do not - have a MX record mail for your hostname, the mail will be delivered to - your host directly.</para> - - <para>Unless you are running your own DNS server, you will not be able - to change any information in the DNS yourself. If you are using an - Internet Provider, speak to them.</para> - </sect2> - - <sect2> - <title>POP Servers</title> - - <para>This program gets the mail from your mailbox and gives it to your - browser. If you want to run a POP server on your computer, you will - need to do 2 things.</para> - - <procedure> - <step> - <para>Get pop software from the <ulink - URL="../ports/mail.html">Ports collection</ulink> that can be - found in <filename>/usr/ports</filename> or packages collection. - This handbook section has a complete reference on the <link - linkend="ports">Ports</link> system.</para> - </step> - - <step> - <para>Modify <filename>/etc/inetd.conf</filename> to load the POP - server.</para> - </step> - </procedure> - - <para>The pop program will have instructions with it. Read them.</para> - </sect2> - </sect1> - - <sect1> - <title>Configuration</title> - - <sect2> - <title>Basic</title> - - <para>As your FreeBSD system comes “out of the box”[TM], you - should be able to send E-mail to external hosts as long as you have - <filename>/etc/resolv.conf</filename> setup or are running a name - server. If you want to have mail for your host delivered to your - specific host,there are two methods:</para> - - <itemizedlist> - <listitem> - <para>Run a name server (<command>man -k named</command>) and have - your own domain <hostid role="domainname">smallminingco.com - </hostid></para> - </listitem> - - <listitem> - <para>Get mail delivered to the current DNS name for your host. Ie: - <hostid role="fqdn">dorm6.ahouse.school.edu </hostid></para> - </listitem> - </itemizedlist> - - <para>No matter what option you choose, to have mail delivered directly - to your host, you must be a full Internet host. You must have a - permanent IP address. IE: NO dynamic PPP. If you are behind a - firewall, the firewall must be passing on smtp traffic to you. From - <filename>/etc/services</filename>:</para> - - <programlisting> -smtp 25/tcp mail #Simple Mail Transfer</programlisting> - - <para>If you want to receive mail at your host itself, you must make - sure that the DNS MX entry points to your host address, or there is no - MX entry for your DNS name.</para> - - <para>Try this:</para> - - <screen>&prompt.root; <userinput>hostname</userinput> -newbsdbox.FreeBSD.org -&prompt.root; <userinput>host newbsdbox.FreeBSD.org</userinput> -newbsdbox.FreeBSD.org has address 204.216.27.xx</screen> - - <para>If that is all that comes out for your machine, mail directory to - <email>root@newbsdbox.FreeBSD.org</email> will work no - problems.</para> - - <para>If instead, you have this:</para> - - <screen>&prompt.root; <userinput>host newbsdbox.FreeBSD.org</userinput> -newbsdbox.FreeBSD.org has address 204.216.27.xx -newbsdbox.FreeBSD.org mail is handled (pri=10) by freefall.FreeBSD.org</screen> - - <para>All mail sent to your host directly will end up on - <hostid>freefall</hostid>, under the same username.</para> - - <para>This information is setup in your domain name server. This should - be the same host that is listed as your primary nameserver in - <filename>/etc/resolv.conf</filename></para> - - <para>The DNS record that carries mail routing information is the Mail - eXchange entry. If no MX entry exists, mail will be delivered directly - to the host by way of the Address record.</para> - - <para>The MX entry for <hostid role="fqdn">freefall.FreeBSD.org</hostid> - at one time.</para> - - <programlisting> -freefall MX 30 mail.crl.net -freefall MX 40 agora.rdrop.com -freefall HINFO Pentium FreeBSD -freefall MX 10 freefall.FreeBSD.org -freefall MX 20 who.cdrom.com -freefall A 204.216.27.xx -freefall CNAME www.FreeBSD.org</programlisting> - - <para><hostid>freefall</hostid> has many MX entries. The lowest MX - number gets the mail in the end. The others will queue mail - temporarily, if <hostid>freefall</hostid> is busy or down.</para> - - <para>Alternate MX sites should have separate connections to the - Internet, to be most useful. An Internet Provider or other friendly - site can provide this service.</para> - - <para><command>dig</command>, <command>nslookup</command>, and - <command>host</command> are your friends.</para> - </sect2> - - <sect2 id="mail-domain"> - <title>Mail for your Domain (Network).</title> - - <para>To setup up a network mailhost, you need to direct the mail from - arriving at all the workstations. In other words, you want to hijack - all mail for <hostid role="domainname">*.smallminingco.com </hostid> - and divert it to one machine, your “mailhost”.</para> - - <para>The network users on their workstations will most likely pick up - their mail over POP or telnet.</para> - - <para>A user account with the <emphasis>same username</emphasis> should - exist on both machines. Please use <command>adduser</command> to do - this as required. If you set the <literal>shell</literal> to - <literal>/nonexistent</literal> the user will not be allowed to - login.</para> - - <para>The mailhost that you will be using must be designated the - Mail eXchange for each workstation. This must be arranged in DNS (ie - BIND, named). Please refer to a Networking book for in-depth - information.</para> - - <para>You basically need to add these lines in your DNS server.</para> - - <programlisting> -pc24.smallminingco.com A <replaceable>xxx.xxx.xxx.xxx</replaceable> ; Workstation ip - MX 10 smtp.smallminingco.com ; Your mailhost</programlisting> - - <para>You cannot do this yourself unless you are running a DNS server. - If you do not want to run a DNS server, get somebody else like your - Internet Provider to do it.</para> - - <para>This will redirect mail for the workstation to the Mail eXchange - host. It does not matter what machine the A record points to, the mail - will be sent to the MX host.</para> - - <para>This feature is used to implement Virtual E-Mail Hosting.</para> - - <para>Example</para> - - <para>I have a customer with domain foo.bar and I want all mail for - foo.bar to be sent to my machine smtp.smalliap.com. You must make an - entry in your DNS server like:</para> - - <programlisting> -foo.bar MX 10 smtp.smalliap.com ; your mailhost</programlisting> - - <para>The A record is not needed if you only want E-Mail for the domain. - IE: Don't expect <command>ping foo.bar</command> to work unless an - Address record for <filename>foo.bar</filename> exists as well.</para> - - <para>On the mailhost that actually accepts mail for final delivery to a - mailbox, <command>sendmail</command> must be told what hosts it will - be accepting mail for.</para> - - <para>Add <literal>pc24.smallminingco.com</literal> to - <filename>/etc/sendmail.cw</filename> (if you are using - <literal>FEATURE(use_cw_file)</literal>), or add a <literal>Cw - myhost.smalliap.com</literal> line to - <filename>/etc/sendmail.cf</filename></para> - - <para>If you plan on doing anything serious with - <command>sendmail</command> you should install the - <command>sendmail</command> source. The source has plenty of - documentation with it. You will find information on getting - <command>sendmail</command> source from <link - linkend="sendmailuucp">the UUCP information</link>.</para> - </sect2> - - <sect2 id="sendmailuucp"> - <title>Setting up UUCP.</title> - - <para><emphasis>Stolen from the FAQ.</emphasis></para> - - <para>The sendmail configuration that ships with FreeBSD is suited for - sites that connect directly to the Internet. Sites that wish to - exchange their mail via UUCP must install another - <command>sendmail</command> configuration file.</para> - - <para>Tweaking <filename>/etc/sendmail.cf</filename> manually is - considered something for purists. Sendmail version 8 comes with a new - approach of generating config files via some <command>m4</command> - preprocessing, where the actual hand-crafted configuration is on a - higher abstraction level. You should use the configuration files under - <filename>/usr/src/usr.sbin/sendmail/cf</filename>.</para> - - <para>If you did not install your system with full sources, the - <command>sendmail</command> config stuff has been broken out into a - separate source distribution tarball just for you. Assuming you have - your CD-ROM mounted, do:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>tar -xvzf /cdrom/dists/src/ssmailcf.aa</userinput></screen> - - <para>Do not panic, this is only a few hundred kilobytes in size. The - file <filename>README</filename> in the <filename>cf</filename> - directory can serve as a basic introduction to m4 - configuration.</para> - - <para>For UUCP delivery, you are best advised to use the - <emphasis>mailertable</emphasis> feature. This constitutes a database - that <command>sendmail</command> can use to base its routing decision - upon.</para> - - <para>First, you have to create your <filename>.mc</filename> file. The - directory <filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the - home of these files. Look around, there are already a few examples. - Assuming you have named your file <filename>foo.mc</filename>, all you - need to do in order to convert it into a valid - <filename>sendmail.cf</filename> is:</para> - - <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail/cf/cf</userinput> -&prompt.root; <userinput>make foo.cf</userinput></screen> - - <para>If you don't have a <filename>/usr/obj</filename> hierarchy, - then:</para> - - <screen>&prompt.root; <userinput>cp foo.cf /etc/sendmail.cf</userinput></screen> - - <para>Otherwise:</para> - - <screen>&prompt.root; <userinput>cp /usr/obj/`pwd`/foo.cf /etc/sendmail.cf</userinput></screen> - - <para>A typical <filename>.mc</filename> file might look like:</para> - - <programlisting> -include(`../m4/cf.m4') -VERSIONID(`<replaceable>Your version number</replaceable>') -OSTYPE(bsd4.4) - -FEATURE(nodns) -FEATURE(nocanonify) -FEATURE(mailertable) - -define(`UUCP_RELAY', <replaceable>your.uucp.relay</replaceable>) -define(`UUCP_MAX_SIZE', 200000) - -MAILER(local) -MAILER(smtp) -MAILER(uucp) - -Cw <replaceable>your.alias.host.name</replaceable> -Cw <replaceable>youruucpnodename.UUCP</replaceable></programlisting> - - <para>The <literal>nodns</literal> and <literal>nocanonify</literal> - features will prevent any usage of the DNS during mail delivery. The - <literal>UUCP_RELAY</literal> clause is needed for bizarre reasons, do - not ask. Simply put an Internet hostname there that is able to handle - .UUCP pseudo-domain addresses; most likely, you will enter the mail - relay of your ISP there.</para> - - <para>Once you have this, you need this file called - <filename>/etc/mailertable</filename>. A typical example of this - gender again:</para> - - <programlisting> -# -# makemap hash /etc/mailertable.db < /etc/mailertable -# -horus.interface-business.de uucp-dom:horus -.interface-business.de uucp-dom:if-bus -interface-business.de uucp-dom:if-bus -.heep.sax.de smtp8:%1 horus.UUCP -uucp-dom:horus if-bus.UUCP -uucp-dom:if-bus . uucp-dom:sax</programlisting> - - <para>As you can see, this is part of a real-life file. The first three - lines handle special cases where domain-addressed mail should not be - sent out to the default route, but instead to some UUCP neighbor in - order to “shortcut” the delivery path. The next line - handles mail to the local Ethernet domain that can be delivered using - SMTP. Finally, the UUCP neighbors are mentioned in the .UUCP - pseudo-domain notation, to allow for a - <literal>uucp-neighbor!recipient</literal> override of the default - rules. The last line is always a single dot, matching everything else, - with UUCP delivery to a UUCP neighbor that serves as your universal - mail gateway to the world. All of the node names behind the - <literal>uucp-dom:</literal> keyword must be valid UUCP neighbors, as - you can verify using the command <command>uuname</command>.</para> - - <para>As a reminder that this file needs to be converted into a DBM - database file before being usable, the command line to accomplish this - is best placed as a comment at the top of the - <filename>mailertable</filename>. You always have to execute this - command each time you change your - <filename>mailertable</filename>.</para> - - <para>Final hint: if you are uncertain whether some particular mail - routing would work, remember the <option>-bt</option> option to - <command>sendmail</command>. It starts <command>sendmail</command> in - “address test mode”; simply enter <literal>0</literal>, - followed by the address you wish to test for the mail routing. The - last line tells you the used internal mail agent, the destination host - this agent will be called with, and the (possibly translated) address. - Leave this mode by typing Control-D.</para> - - <screen>&prompt.user; <userinput>sendmail -bt</userinput> -ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) -Enter <ruleset> <address> -<prompt>></prompt> <userinput>0 foo@interface-business.de</userinput> -rewrite: ruleset 0 input: foo @ interface-business . de -… -rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo < @ interface-business . de</screen> - </sect2> - </sect1> - - <sect1 id="mailfaq"> - <title>FAQ</title> - - <para><emphasis>Migration from FAQ.</emphasis></para> - - <sect2> - <title>Why do I have to use the FQDN for hosts on my site?</title> - - <para>You will probably find that the host is actually in a different - domain; for example, if you are in <hostid - role="fqdn">foo.bar.edu</hostid> and you wish to reach a host called - <hostid>mumble</hostid> in the <hostid - role="domainname">bar.edu</hostid> domain, you will have to refer to - it by the fully-qualified domain name, <hostid - role="fqdn">mumble.bar.edu</hostid>, instead of just - <hostid>mumble</hostid>.</para> - - <para>Traditionally, this was allowed by BSD BIND resolvers. However the - current version of <application>BIND</application> that ships with - FreeBSD no longer provides default abbreviations for non-fully - qualified domain names other than the domain you are in. So an - unqualified host <hostid>mumble</hostid> must either be found as - <hostid role="fqdn">mumble.foo.bar.edu</hostid>, or it will be - searched for in the root domain.</para> - - <para>This is different from the previous behavior, where the search - continued across <hostid role="domainname">mumble.bar.edu</hostid>, - and <hostid role="domainname">mumble.edu</hostid>. Have a look at RFC - 1535 for why this was considered bad practice, or even a security - hole.</para> - - <para>As a good workaround, you can place the line - - <programlisting> -search foo.bar.edu bar.edu</programlisting> - - instead of the previous - - <programlisting> -domain foo.bar.edu</programlisting> - - into your <filename>/etc/resolv.conf</filename>. However, make sure - that the search order does not go beyond the “boundary between - local and public administration”, as RFC 1535 calls it.</para> - </sect2> - - <sect2> - <title>Sendmail says <errorname>mail loops back to - myself</errorname></title> - - <para>This is answered in the sendmail FAQ as follows:</para> - - <programlisting> -* I am getting "Local configuration error" messages, such as: - -553 relay.domain.net config error: mail loops back to myself -554 <user@domain.net>... Local configuration error - -How can I solve this problem? - -You have asked mail to the domain (e.g., domain.net) to be -forwarded to a specific host (in this case, relay.domain.net) -by using an MX record, but the relay machine does not recognize -itself as domain.net. Add domain.net to /etc/sendmail.cw -(if you are using FEATURE(use_cw_file)) or add "Cw domain.net" -to /etc/sendmail.cf.</programlisting> - - <para>The sendmail FAQ is in - <filename>/usr/src/usr.sbin/sendmail</filename> and is recommended - reading if you want to do any “tweaking” of your mail - setup.</para> - </sect2> - - <sect2> - <title>How can I do E-Mail with a dialup PPP host?</title> - - <para>You want to connect a FreeBSD box on a lan, to the Internet. The - FreeBSD box will be a mail gateway for the lan. The PPP connection is - non-dedicated.</para> - - <para>There are at least two way to do this.</para> - - <para>The other is to use UUCP.</para> - - <para>The key is to get a Internet site to provide secondary MX services - for your domain. For example:</para> - - <programlisting> -bigco.com. MX 10 bigco.com. - MX 20 smalliap.com.</programlisting> - - <para>Only one host should be specified as the final recipient ( add - <literal>Cw bigco.com</literal> in - <filename>/etc/sendmail.cf</filename> on bigco.com).</para> - - <para>When the senders <command>sendmail</command> is trying to deliver - the mail it will try to connect to you over the modem link. It will - most likely time out because you are not online. - <command>sendmail</command> will automatically deliver it to the - secondary MX site, ie your Internet provider. The secondary MX site - will try every (<literal>sendmail_flags = "-bd -q15m"</literal> in - <filename>/etc/rc.conf</filename> ) 15 minutes to connect to your host - to deliver the mail to the primary MX site.</para> - - <para>You might want to use something like this as a login - script.</para> - - <programlisting> -#!/bin/sh -# Put me in /usr/local/bin/pppbigco -( sleep 60 ; /usr/sbin/sendmail -q ) & -/usr/sbin/ppp -direct pppbigco</programlisting> - - <para>If you are going to create a separate login script for a user you - could use <command>sendmail -qRbigco.com</command> instead in the - script above. This will force all mail in your queue for bigco.com to - be processed immediately.</para> - - <para>A further refinement of the situation is as follows.</para> - - <para>Message stolen from the freebsd-isp mailing list.</para> - - <programlisting> -> we provide the secondary mx for a customer. The customer connects to -> our services several times a day automatically to get the mails to -> his primary mx (We do not call his site when a mail for his domains -> arrived). Our sendmail sends the mailqueue every 30 minutes. At the -> moment he has to stay 30 minutes online to be sure that all mail is -> gone to the primary mx. -> -> Is there a command that would initiate sendmail to send all the mails -> now? The user has not root-privileges on our machine of course. - -In the 'privacy flags' section of sendmail.cf, there is a definition -Opgoaway,restrictqrun - -Remove restrictqrun to allow non-root users to start the queue processing. -You might also like to rearrange the MXs. We are the 1st MX for our -customers like this, and we have defined: - -# If we are the best MX for a host, try directly instead of generating -# local config error. -OwTrue - -That way a remote site will deliver straight to you, without trying -the customer connection. You then send to your customer. Only works for -"hosts", so you need to get your customer to name their mail machine -"customer.com" as well as "hostname.customer.com" in the DNS. Just put -an A record in the DNS for "customer.com".</programlisting> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/mailing-lists.ent b/en/handbook/mailing-lists.ent deleted file mode 100644 index 4a59f66dfe..0000000000 --- a/en/handbook/mailing-lists.ent +++ /dev/null @@ -1,104 +0,0 @@ -<!-- - Names of FreeBSD mailing lists and related software. - - $Id: mailing-lists.ent,v 1.3 1999-07-28 20:23:05 nik Exp $ ---> - -<!ENTITY a.advocacy "FreeBSD advocacy mailing list - <email>freebsd-advocacy@FreeBSD.org</email>"> - -<!ENTITY a.announce "FreeBSD announcements mailing list - <email>freebsd-announce@FreeBSD.org</email>"> - -<!ENTITY a.bugs "FreeBSD problem reports mailing list - <email>freebsd-bugs@FreeBSD.org</email>"> - -<!ENTITY a.chat "FreeBSD chat mailing list - <email>freebsd-chat@FreeBSD.org</email>"> - -<!ENTITY a.core "FreeBSD core team - <email>freebsd-core@FreeBSD.org</email>"> - -<!ENTITY a.current "FreeBSD-current mailing list - <email>freebsd-current@FreeBSD.org</email>"> - -<!ENTITY a.cvsall "FreeBSD CVS commit message mailing list - <email>cvs-all@FreeBSD.org</email>"> - -<!ENTITY a.database "FreeBSD based Databases mailing list - <email>freebsd-database@FreeBSD.org</email>"> - -<!ENTITY a.doc "FreeBSD documentation project mailing list - <email>freebsd-doc@FreeBSD.org</email>"> - -<!ENTITY a.emulation "FreeBSD-emulation mailing list - <email>freebsd-emulation@FreeBSD.org</email>"> - -<!ENTITY a.fs "FreeBSD filesystem project mailing list - <email>freebsd-fs@FreeBSD.org</email>"> - -<!ENTITY a.hackers "FreeBSD technical discussions mailing list - <email>freebsd-hackers@FreeBSD.org</email>"> - -<!ENTITY a.hardware "FreeBSD hardware and equipment mailing list - <email>freebsd-hardware@FreeBSD.org</email>"> - -<!ENTITY a.isdn "FreeBSD ISDN mailing list - <email>freebsd-isdn@FreeBSD.org</email>"> - -<!ENTITY a.isp "FreeBSD Internet service provider's mailing list - <email>freebsd-isp@FreeBSD.org</email>"> - -<!ENTITY a.java "FreeBSD Java Language mailing list - <email>freebsd-java@FreeBSD.org</email>"> - -<!ENTITY a.jobs "FreeBSD related employment mailing list - <email>freebsd-jobs@FreeBSD.org</email>"> - -<!ENTITY a.mobile "FreeBSD laptop computer mailing list - <email>freebsd-mobile@FreeBSD.org</email>"> - -<!ENTITY a.mozilla "FreeBSD port of the Mozilla browser mailing list - <email>freebsd-mozilla@FreeBSD.org</email>"> - -<!ENTITY a.multimedia "FreeBSD multimedia mailing list - <email>freebsd-multimedia@FreeBSD.org</email>"> - -<!ENTITY a.net "FreeBSD networking mailing list - <email>freebsd-net@FreeBSD.org</email>"> - -<!ENTITY a.newbies "FreeBSD new users mailing list - <email>freebsd-newbies@FreeBSD.org</email>"> - -<!ENTITY a.newbus "New Bus Architecture mailing list - <email>new-bus-arch@bostonradio.org</email>"> - -<!ENTITY a.ports "FreeBSD ports mailing list - <email>freebsd-ports@FreeBSD.org</email>"> - -<!ENTITY a.questions "FreeBSD general questions mailing list - <email>freebsd-questions@FreeBSD.org</email>"> - -<!ENTITY a.scsi "FreeBSD SCSI subsystem mailing list - <email>freebsd-scsi@FreeBSD.org</email>"> - -<!ENTITY a.security "FreeBSD security mailing list - <email>freebsd-security@FreeBSD.org</email>"> - -<!ENTITY a.security-notifications "FreeBSD security notifications mailing list - <email>freebsd-security-notifications@FreeBSD.org</email>"> - -<!ENTITY a.small "FreeBSD-small mailing list - <email>freebsd-small@FreeBSD.org</email>"> - -<!ENTITY a.smp "FreeBSD symmetric multiprocessing mailing list - <email>freebsd-smp@FreeBSD.org</email>"> - -<!ENTITY a.stable "FreeBSD-stable mailing list - <email>freebsd-stable@FreeBSD.org</email>"> - -<!ENTITY a.tokenring "FreeBSD tokenring mailing list - <email>freebsd-tokenring@FreeBSD.org</email>"> - -<!ENTITY a.majordomo "<email>majordomo@FreeBSD.org</email>"> - diff --git a/en/handbook/mirrors/chapter.sgml b/en/handbook/mirrors/chapter.sgml deleted file mode 100644 index 97e1d513ec..0000000000 --- a/en/handbook/mirrors/chapter.sgml +++ /dev/null @@ -1,1492 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.25 1999-08-11 22:37:59 nik Exp $ ---> - -<chapter id="mirrors"> - <title>Obtaining FreeBSD</title> - - <sect1> - <title>CD-ROM Publishers</title> - - <para>FreeBSD is available on CD-ROM from Walnut Creek CDROM: - - <address> - <otheraddr>Walnut Creek CDROM</otheraddr> - <street>4041 Pike Lane, Suite F</street> - <city>Concord</city> - <state>CA</state>, <postcode>94520</postcode> - <country>USA</country> - Phone: <phone>+1 925 674-0783</phone> - Fax: <fax>+1 925 674-0821</fax> - Email: <email>info@cdrom.com</email> - WWW: <otheraddr>http://www.cdrom.com/</otheraddr> - </address></para> - </sect1> - - <sect1 id="mirrors-ftp"> - <title>FTP Sites</title> - - <para>The official sources for FreeBSD are available via anonymous FTP - from: - - <blockquote> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD">ftp://ftp.FreeBSD.org/pub/FreeBSD</ulink>.</para> - </blockquote></para> - - <para>The <ulink - url="http://www.itworks.com.au/~gavin/FBSDsites.php3">FreeBSD mirror - sites database</ulink> is more accurate than the mirror listing in the - handbook, as it gets its information form the DNS rather than relying on - static lists of hosts.</para> - - <para>Additionally, FreeBSD is available via anonymous FTP from the - following mirror sites. If you choose to obtain FreeBSD via anonymous - FTP, please try to use a site near you.</para> - - <para><link linkend="mirrors-ar">Argentina</link>, - <link linkend="mirrors-au">Australia</link>, - <link linkend="mirrors-br">Brazil</link>, - <link linkend="mirrors-ca">Canada</link>, - <link linkend="mirrors-cn">China</link>, - <link linkend="mirrors-cz">Czech Republic</link>, - <link linkend="mirrors-dk">Denmark</link>, - <link linkend="mirrors-ee">Estonia</link>, - <link linkend="mirrors-fi">Finland</link>, - <link linkend="mirrors-fr">France</link>, - <link linkend="mirrors-de">Germany</link>, - <link linkend="mirrors-hk">Hong Kong</link>, - <link linkend="mirrors-ie">Ireland</link>, - <link linkend="mirrors-il">Israel</link>, - <link linkend="mirrors-jp">Japan</link>, - <link linkend="mirrors-kr">Korea</link>, - <link linkend="mirrors-nl">Netherlands</link>, - <link linkend="mirrors-nz">New Zealand</link>, - <link linkend="mirrors-pl">Poland</link>, - <link linkend="mirrors-pt">Portugal</link>, - <link linkend="mirrors-ru">Russia</link>, - <link linkend="mirrors-sa">Saudi Arabia</link>, - <link linkend="mirrors-za">South Africa</link>, - <link linkend="mirrors-es">Spain</link>, - <link linkend="mirrors-sk">Slovak Republic</link>, - <link linkend="mirrors-si">Slovenia</link>, - <link linkend="mirrors-se">Sweden</link>, - <link linkend="mirrors-tw">Taiwan</link>, - <link linkend="mirrors-th">Thailand</link>, - <link linkend="mirrors-uk">UK</link>, - <link linkend="mirrors-ua">Ukraine</link>, - <link linkend="mirrors-us">USA</link>.</para> - - <variablelist> - <varlistentry> - <term><anchor id="mirrors-ar">Argentina</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ar.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.ar.FreeBSD.org/pub/FreeBSD">ftp://ftp.ar.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-au">Australia</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@au.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.au.FreeBSD.org/pub/FreeBSD">ftp://ftp.au.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.au.FreeBSD.org/pub/FreeBSD">ftp://ftp2.au.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.au.FreeBSD.org/pub/FreeBSD">ftp://ftp3.au.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp4.au.FreeBSD.org/pub/FreeBSD">ftp://ftp4.au.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-br">Brazil</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@br.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.br.FreeBSD.org/pub/FreeBSD">ftp://ftp.br.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.br.FreeBSD.org/pub/FreeBSD">ftp://ftp2.br.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.br.FreeBSD.org/pub/FreeBSD">ftp://ftp3.br.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp4.br.FreeBSD.org/pub/FreeBSD">ftp://ftp4.br.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp5.br.FreeBSD.org/pub/FreeBSD">ftp://ftp5.br.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp6.br.FreeBSD.org/pub/FreeBSD">ftp://ftp6.br.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp7.br.FreeBSD.org/pub/FreeBSD">ftp://ftp7.br.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ca">Canada</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ca.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.ca.FreeBSD.org/pub/FreeBSD">ftp://ftp.ca.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-cn">China</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>phj@cn.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.cn/FreeBSD.org/pub/FreeBSD">ftp://ftp.cn.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-cz">Czech Republic</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@cz.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.cz.FreeBSD.org/pub/FreeBSD">ftp://ftp.cz.FreeBSD.org</ulink> Contact: <email>calda@dzungle.ms.mff.cuni.cz</email></para> - </listitem> - <listitem> - <para><ulink - URL="ftp://sunsite.mff.cuni.cz/OS/FreeBSD">ftp://sunsite.mff.cuni.cz/OS/FreeBSD</ulink> Contact: <email>jj@sunsite.mff.cuni.cz</email>.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-dk">Denmark</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@dk.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD">ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ee">Estonia</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ee.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.ee.FreeBSD.org/pub/FreeBSD">ftp://ftp.ee.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-fi">Finland</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@fi.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.fi.FreeBSD.org/pub/FreeBSD">ftp://ftp.fi.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-fr">France</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@fr.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.fr.FreeBSD.org/pub/FreeBSD">ftp://ftp.fr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp2.fr.FreeBSD.org/pub/FreeBSD">ftp://ftp2.fr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp3.fr.FreeBSD.org/pub/FreeBSD">ftp://ftp3.fr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-de">Germany</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@de.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.de.FreeBSD.org/pub/FreeBSD">ftp://ftp.de.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.de.FreeBSD.org/pub/FreeBSD">ftp://ftp2.de.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.de.FreeBSD.org/pub/FreeBSD">ftp://ftp3.de.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp4.de.FreeBSD.org/pub/FreeBSD">ftp://ftp4.de.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp5.de.FreeBSD.org/pub/FreeBSD">ftp://ftp5.de.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp6.de.FreeBSD.org/pub/FreeBSD">ftp://ftp6.de.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp7.de.FreeBSD.org/pub/FreeBSD">ftp://ftp7.de.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-hk">Hong Kong</term> - - <listitem> - <itemizedlist> - - <listitem> - <para><ulink - URL="ftp://ftp.hk.super.net/pub/FreeBSD">ftp://ftp.hk.super.net/pub/FreeBSD</ulink> Contact: <email>ftp-admin@HK.Super.NET</email>.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ie">Ireland</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ie.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.ie.FreeBSD.org/pub/FreeBSD">ftp://ftp.ie.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-il">Israel</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@il.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.il.FreeBSD.org/pub/FreeBSD">ftp://ftp.il.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.il.FreeBSD.org/pub/FreeBSD">ftp://ftp2.il.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-jp">Japan</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@jp.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.jp.FreeBSD.org/pub/FreeBSD">ftp://ftp.jp.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.jp.FreeBSD.org/pub/FreeBSD">ftp://ftp2.jp.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.jp.FreeBSD.org/pub/FreeBSD">ftp://ftp3.jp.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp4.jp.FreeBSD.org/pub/FreeBSD">ftp://ftp4.jp.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp5.jp.FreeBSD.org/pub/FreeBSD">ftp://ftp5.jp.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp6.jp.FreeBSD.org/pub/FreeBSD">ftp://ftp6.jp.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-kr">Korea</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@kr.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.kr.FreeBSD.org/pub/FreeBSD">ftp://ftp.kr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.kr.FreeBSD.org/pub/FreeBSD">ftp://ftp2.kr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp3.kr.FreeBSD.org/pub/FreeBSD">ftp://ftp3.kr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp4.kr.FreeBSD.org/pub/FreeBSD">ftp://ftp4.kr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp5.kr.FreeBSD.org/pub/FreeBSD">ftp://ftp5.kr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp6.kr.FreeBSD.org/pub/FreeBSD">ftp://ftp6.kr.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-nl">Netherlands</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@nl.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.nl.FreeBSD.org/pub/FreeBSD">ftp://ftp.nl.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-nz">New Zealand</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@nz.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink url="ftp://ftp.nz.FreeBSD.org/pub/FreeBSD">ftp://ftp.nz.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-pl">Poland</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@pl.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.pl.FreeBSD.org/pub/FreeBSD">ftp://ftp.pl.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-pt">Portugal</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@pt.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.pt.FreeBSD.org/pub/FreeBSD">ftp://ftp.pt.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.pt.FreeBSD.org/pub/FreeBSD">ftp://ftp2.pt.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ru">Russia</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ru.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.ru.FreeBSD.org/pub/FreeBSD">ftp://ftp.ru.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.ru.FreeBSD.org/pub/FreeBSD">ftp://ftp2.ru.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.ru.FreeBSD.org/pub/FreeBSD">ftp://ftp3.ru.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp4.ru.FreeBSD.org/pub/FreeBSD">ftp://ftp4.ru.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-sa">Saudi Arabia</term> - <listitem> - <para>In case of problems, please contact - <email>ftpadmin@isu.net.sa</email></para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.isu.net.sa/pub/mirrors/ftp.freebsd.org/">ftp://ftp.isu.net.sa/pub/mirrors/ftp.freebsd.org</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - - <varlistentry> - <term><anchor id="mirrors-za">South Africa</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@za.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.za.FreeBSD.org/pub/FreeBSD">ftp://ftp.za.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.za.FreeBSD.org/pub/FreeBSD">ftp://ftp2.za.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.za.FreeBSD.org/FreeBSD">ftp://ftp3.za.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-sk">Slovak Republic</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@sk.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink url="ftp://ftp.sk.FreeBSD.org/pub/FreeBSD">ftp://ftp.sk.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry><term><anchor id="mirrors-si">Slovenia</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@si.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.si.FreeBSD.org/pub/FreeBSD">ftp://ftp.si.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-es">Spain</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@es.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink url="ftp://ftp.es.FreeBSD.org/pub/FreeBSD">ftp://ftp.es.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-se">Sweden</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@se.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.se.FreeBSD.org/pub/FreeBSD">ftp://ftp.se.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.se.FreeBSD.org/pub/FreeBSD">ftp://ftp2.se.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.se.FreeBSD.org/pub/FreeBSD">ftp://ftp3.se.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-tw">Taiwan</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@tw.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.tw.FreeBSD.org/pub/FreeBSD">ftp://ftp.tw.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.tw.FreeBSD.org/pub/FreeBSD">ftp://ftp2.tw.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.tw.FreeBSD.org/pub/FreeBSD">ftp://ftp3.tw.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-th">Thailand</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.nectec.or.th/pub/FreeBSD">ftp://ftp.nectec.or.th/pub/FreeBSD</ulink> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ua">Ukraine</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.ua.FreeBSD.org/pub/FreeBSD">ftp://ftp.ua.FreeBSD.org/pub/FreeBSD</ulink> Contact: <email>freebsd-mnt@lucky.net</email>.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-uk">UK</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@uk.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.uk.FreeBSD.org/pub/FreeBSD">ftp://ftp.uk.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.uk.FreeBSD.org/pub/FreeBSD">ftp://ftp2.uk.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.uk.FreeBSD.org/pub/FreeBSD">ftp://ftp3.uk.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp4.uk.FreeBSD.org/pub/FreeBSD">ftp://ftp4.uk.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-us">USA</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD">ftp://ftp.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.FreeBSD.org/pub/FreeBSD">ftp://ftp2.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp3.FreeBSD.org/pub/FreeBSD">ftp://ftp3.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp4.FreeBSD.org/pub/FreeBSD">ftp://ftp4.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp5.FreeBSD.org/pub/FreeBSD">ftp://ftp5.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp6.FreeBSD.org/pub/FreeBSD">ftp://ftp6.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - <para>The latest versions of export-restricted code for FreeBSD (2.0C or - later) (eBones and secure) are being made available at the following - locations. If you are outside the U.S. or Canada, please get secure - (DES) and eBones (Kerberos) from one of the following foreign - distribution sites:</para> - - <variablelist> - <varlistentry> - <term>South Africa</term> - - <listitem> - <para>Hostmaster <email>hostmaster@internat.FreeBSD.org</email> for - this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.internat.FreeBSD.org/pub/FreeBSD">ftp://ftp.internat.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp2.internat.FreeBSD.org/pub/FreeBSD">ftp://ftp2.internat.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Brazil</term> - - <listitem> - <para>Hostmaster <email>hostmaster@br.FreeBSD.org</email> for this - domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.br.FreeBSD.org/pub/FreeBSD">ftp://ftp.br.FreeBSD.org/pub/FreeBSD</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Finland</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt">ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt</ulink> Contact: <email>count@nic.funet.fi</email>.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="mirrors-ctm"> - <title>CTM Sites</title> - - <para><link linkend="ctm">CTM</link>/FreeBSD is available via anonymous - FTP from the following mirror sites. If you choose to obtain CTM via - anonymous FTP, please try to use a site near you.</para> - - <para>In case of problems, please contact &a.phk;.</para> - - <variablelist> - <varlistentry> - <term>California, Bay Area, official source</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Germany, Trier</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM">ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>South Africa, backup server for old deltas</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ftp.internat.FreeBSD.org/pub/FreeBSD/CTM">ftp://ftp.internat.FreeBSD.org/pub/FreeBSD/CTM</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Taiwan/R.O.C, Chiayi</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - URL="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/CTM">ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/CTM</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/CTM">ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/CTM</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/CTM">ftp://ctm3.tw.FreeBSD.org/pub/freebsd/CTM</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - <para>If you did not find a mirror near to you or the mirror is - incomplete, try <ulink URL="http://ftpsearch.ntnu.no/">FTP - search</ulink> at <ulink - URL="http://ftpsearch.ntnu.no/ftpsearch/">http://ftpsearch.ntnu.no/ftpsearch</ulink>. - FTP search is a great free archie server in Trondheim, Norway.</para> - </sect1> - - <sect1 id="mirrors-cvsup"> - <title>CVSup Sites</title> - - <para><link linkend="cvsup">CVSup</link> servers for FreeBSD are running - at the following sites:</para> - - <variablelist> - <varlistentry> - <term>Argentina</term> - - <listitem> - <itemizedlist> - - <listitem> - <para>cvsup.ar.FreeBSD.org (maintainer - <email>msagre@cactus.fi.uba.ar</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Australia</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.au.FreeBSD.org (maintainer - <email>dawes@physics.usyd.edu.au</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Brazil</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.br.FreeBSD.org (maintainer - <email>cvsup@cvsup.br.FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.br.FreeBSD.org (maintainer - <email>tps@ti.sk</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Canada</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.ca.FreeBSD.org (maintainer - <email>dan@jaded.net</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>China</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.cn.FreeBSD.org (maintainer - <email>phj@cn.FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Czech Republic</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.cz.FreeBSD.org (maintainer - <email>cejkar@dcse.fee.vutbr.cz</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Denmark</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.dk.FreeBSD.org (maintainer - <email>jesper@skriver.dk</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Estonia</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.ee.FreeBSD.org (maintainer - <email>taavi@uninet.ee</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Finland</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.fi.FreeBSD.org (maintainer - <email>count@key.sms.fi</email>)</para> - </listitem> - - <listitem> - <para>cvsip2.fi.FreeBSD.org (maintainer - <email>count@key.sms.fi</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>France</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.fr.FreeBSD.org (maintainer - <email>hostmaster@fr.FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Germany</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.de.FreeBSD.org (maintainer - <email>wosch@FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.de.FreeBSD.org (maintainer - <email>petzi@FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.de.FreeBSD.org (maintainer - <email>ag@leo.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Iceland</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.is.FreeBSD.org (maintainer - <email>adam@veda.is</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Japan</term> - - <listitem> - <itemizedlist> - - <listitem> - <para>cvsup.jp.FreeBSD.org (maintainer - <email>simokawa@sat.t.u-tokyo.ac.jp</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.jp.FreeBSD.org (maintainer - <email>max@FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.jp.FreeBSD.org (maintainer - <email>shige@cin.nihon-u.ac.jp</email>)</para> - </listitem> - - <listitem> - <para>cvsup4.jp.FreeBSD.org (maintainer - <email>cvsup-admin@ftp.media.kyoto-u.ac.jp</email>)</para> - </listitem> - - <listitem> - <para>cvsup5.jp.FreeBSD.org (maintainer - <email>cvsup@imasy.or.jp</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Korea</term> - - <listitem> - <itemizedlist> - - <listitem> - <para>cvsup.kr.FreeBSD.org (maintainer - <email>cjh@kr.FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Netherlands</term> - - <listitem> - <itemizedlist> - - <listitem> - <para>cvsup.nl.FreeBSD.org (maintainer - <email>xaa@xaa.iae.nl</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Norway</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.no.FreeBSD.org (maintainer - <email>Tor.Egge@idt.ntnu.no</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Poland</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.pl.FreeBSD.org (maintainer - <email>Mariusz@kam.pl</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Russia</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.ru.FreeBSD.org (maintainer - <email>mishania@demos.su</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.ru.FreeBSD.org (maintainer - <email>dv@dv.ru</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Spain</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.es.FreeBSD.org (maintainer - <email>jesusr@FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Sweden</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.se.FreeBSD.org (maintainer - <email>pantzer@ludd.luth.se</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Slovak Republic</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.sk.FreeBSD.org (maintainer - <email>tps@tps.sk</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.sk.FreeBSD.org (maintainer - <email>tps@tps.sk</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>South Africa</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.za.FreeBSD.org (maintainer - <email>markm@FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.za.FreeBSD.org (maintainer - <email>markm@FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Taiwan</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.tw.FreeBSD.org (maintainer - <email>jdli@freebsd.csie.nctu.edu.tw</email>)</para> - </listitem> - - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Ukraine</term> - - <listitem> - <itemizedlist> - - <listitem> - <para>cvsup2.ua.FreeBSD.org (maintainer - <email>freebsd-mnt@lucky.net</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>United Kingdom</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.uk.FreeBSD.org (maintainer - <email>joe@pavilion.net</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.uk.FreeBSD.org (maintainer - <email>brian@FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>USA</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup1.FreeBSD.org (maintainer - <email>skynyrd@opus.cts.cwu.edu</email>), Washington - state</para> - </listitem> - - <listitem> - <para>cvsup2.FreeBSD.org (maintainer - <email>jdp@FreeBSD.org</email>), California</para> - </listitem> - - <listitem> - <para>cvsup3.FreeBSD.org (maintainer - <email>wollman@FreeBSD.org</email>), Massachusetts</para> - </listitem> - - <listitem> - <para>cvsup5.FreeBSD.org (maintainer - <email>ck@adsu.bellsouth.com</email>), Georgia</para> - </listitem> - - <listitem> - <para>cvsup6.FreeBSD.org (maintainer - <email>jdp@FreeBSD.org</email>), Florida</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - <para>The export-restricted code for FreeBSD (eBones and secure) is - available via <application>CVSup</application> at the following - international repository. Please use this site to get the - export-restricted code, if you are outside the USA or Canada.</para> - - <variablelist> - <varlistentry> - <term>South Africa</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.internat.FreeBSD.org (maintainer - <email>markm@FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - <para>The following <application>CVSup</application> site is especially - designed for <link linkend="ctm">CTM</link> users. Unlike the other - CVSup mirrors, it is kept up-to-date by <application>CTM</application>. - That means if you <application>CVSup</application> - <literal>cvs-all</literal> with <literal>release=cvs</literal> from this - site, you get a version of the repository (including the inevitable - <filename>.ctm_status</filename> file) which is suitable for being - updated using the <application>CTM</application> - <literal>cvs-cur</literal> deltas. This allows users who track the - entire <literal>cvs-all</literal> tree to go from - <application>CVSup</application> to <application>CTM</application> - without having to rebuild their repository from scratch using a fresh - <application>CTM</application> base delta.</para> - - <note> - <para>This special feature only works for the <literal>cvs-all</literal> - distribution with <command>cvs</command> as the release tag. - CVSupping any other distribution and/or release will get you the - specified distribution, but it will not be suitable for - <application>CTM</application> updating.</para> - </note> - - <note> - <para>Because the current version of <application>CTM</application> does - not preserve the timestamps of files, the timestamps at this mirror - site are not the same as those at other mirror sites. Switching - between this site and other sites is not recommended. It will work - correctly, but will be somewhat inefficient.</para> - </note> - - <variablelist> - <varlistentry> - <term>Germany</term> - - <listitem> - <itemizedlist> - <listitem> - <para>ctm.FreeBSD.org (maintainer - <email>blank@fox.uni-trier.de</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="mirrors-afs"> - <title>AFS Sites</title> - - <para>AFS servers for FreeBSD are running at the following sites;</para> - - <variablelist> - <varlistentry> - <term>Sweden</term> - - <listitem> - <para>The path to the files are: - <filename>/afs/stacken.kth.se/ftp/pub/FreeBSD</filename></para> - - <programlisting> -stacken.kth.se # Stacken Computer Club, KTH, Sweden -130.237.234.43 #hot.stacken.kth.se -130.237.237.230 #fishburger.stacken.kth.se -130.237.234.3 #milko.stacken.kth.se</programlisting> - - <para>Maintainer <email>ftp@stacken.kth.se</email></para> - </listitem> - </varlistentry> - </variablelist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/newsgroups.ent b/en/handbook/newsgroups.ent deleted file mode 100644 index 0c1a8b9821..0000000000 --- a/en/handbook/newsgroups.ent +++ /dev/null @@ -1,10 +0,0 @@ -<!-- - Names of FreeBSD newsgroups - - $Id: newsgroups.ent,v 1.1 1999-03-04 22:14:06 nik Exp $ ---> - -<!ENTITY ng.misc "the - <ulink url='news:comp.unix.bsd.freebsd.misc'>comp.unix.bsd.freebsd.misc</ulink> - newsgroup"> - diff --git a/en/handbook/pgpkeys/chapter.sgml b/en/handbook/pgpkeys/chapter.sgml deleted file mode 100644 index 53e2f8a6d6..0000000000 --- a/en/handbook/pgpkeys/chapter.sgml +++ /dev/null @@ -1,624 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.13 1999-07-28 20:23:29 nik Exp $ ---> - -<chapter id="pgpkeys"> - <title>PGP keys</title> - - <para>In case you need to verify a signature or send encrypted email to one - of the officers or core team members a number of keys are provided here - for your convenience.</para> - - <sect1> - <title>Officers</title> - - <sect2> - <title>FreeBSD Security Officer - <email>security-officer@FreeBSD.org</email></title> - - <programlisting> -FreeBSD Security Officer <security-officer@FreeBSD.org> -Fingerprint = 41 08 4E BB DB 41 60 71 F9 E5 0E 98 73 AF 3F 11 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3i - -mQCNAzF7MY4AAAEEAK7qBgPuBejER5HQbQlsOldk3ZVWXlRj54raz3IbuAUrDrQL -h3g57T9QY++f3Mot2LAf5lDJbsMfWrtwPrPwCCFRYQd6XH778a+l4ju5axyjrt/L -Ciw9RrOC+WaPv3lIdLuqYge2QRC1LvKACIPNbIcgbnLeRGLovFUuHi5z0oilAAUR -tDdGcmVlQlNEIFNlY3VyaXR5IE9mZmljZXIgPHNlY3VyaXR5LW9mZmljZXJAZnJl -ZWJzZC5vcmc+iQCVAwUQMX6yrOJgpPLZnQjrAQHyowQA1Nv2AY8vJIrdp2ttV6RU -tZBYnI7gTO3sFC2bhIHsCvfVU3JphfqWQ7AnTXcD2yPjGcchUfc/EcL1tSlqW4y7 -PMP4GHZp9vHog1NAsgLC9Y1P/1cOeuhZ0pDpZZ5zxTo6TQcCBjQA6KhiBFP4TJql -3olFfPBh3B/Tu3dqmEbSWpuJAJUDBRAxez3C9RVb+45ULV0BAak8A/9JIG/jRJaz -QbKom6wMw852C/Z0qBLJy7KdN30099zMjQYeC9PnlkZ0USjQ4TSpC8UerYv6IfhV -nNY6gyF2Hx4CbEFlopnfA1c4yxtXKti1kSN6wBy/ki3SmqtfDhPQ4Q31p63cSe5A -3aoHcjvWuqPLpW4ba2uHVKGP3g7SSt6AOYkAlQMFEDF8mz0ff6kIA1j8vQEBmZcD -/REaUPDRx6qr1XRQlMs6pfgNKEwnKmcUzQLCvKBnYYGmD5ydPLxCPSFnPcPthaUb -5zVgMTjfjS2fkEiRrua4duGRgqN4xY7VRAsIQeMSITBOZeBZZf2oa9Ntidr5PumS -9uQ9bvdfWMpsemk2MaRG9BSoy5Wvy8VxROYYUwpT8Cf2iQCVAwUQMXsyqWtaZ42B -sqd5AQHKjAQAvolI30Nyu3IyTfNeCb/DvOe9tlOn/o+VUDNJiE/PuBe1s2Y94a/P -BfcohpKC2kza3NiW6lLTp00OWQsuu0QAPc02vYOyseZWy4y3Phnw60pWzLcFdemT -0GiYS5Xm1o9nAhPFciybn9j1q8UadIlIq0wbqWgdInBT8YI/l4f5sf6JAJUDBRAx -ezKXVS4eLnPSiKUBAc5OBACIXTlKqQC3B53qt7bNMV46m81fuw1PhKaJEI033mCD -ovzyEFFQeOyRXeu25Jg9Bq0Sn37ynISucHSmt2tUD5W0+p1MUGyTqnfqejMUWBzO -v4Xhp6a8RtDdUMBOTtro16iulGiRrCKxzVgEl4i+9Z0ZiE6BWlg5AetoF5n3mGk1 -lw== -=ipyA ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.imp;</title> - - <programlisting> -Warner Losh <imp@village.org> - aka <imp@FreeBSD.org> -Fingerprint = D4 31 FD B9 F7 90 17 E8 37 C5 E7 7F CF A6 C1 B9 ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzDzTiAAAAEEAK8D7KWEbVFUrmlqhUEnAvphNIqHEbqqT8s+c5f5c2uHtlcH -V4mV2TlUaDSVBN4+/D70oHmZc4IgiQwMPCWRrSezg9z/MaKlWhaslc8YT6Xc1q+o -EP/fAdKUrq49H0QQbkQk6Ks5wKW6v9AOvdmsS6ZJEcet6d9G4dxynu/2qPVhAAUR -tCBNLiBXYXJuZXIgTG9zaCA8aW1wQHZpbGxhZ2Uub3JnPokAlQMFEDM/SK1VLh4u -c9KIpQEBFPsD/1n0YuuUPvD4CismZ9bx9M84y5sxLolgFEfP9Ux196ZSeaPpkA0g -C9YX/IyIy5VHh3372SDWN5iVSDYPwtCmZziwIV2YxzPtZw0nUu82P/Fn8ynlCSWB -5povLZmgrWijTJdnUWI0ApVBUTQoiW5MyrNN51H3HLWXGoXMgQFZXKWYiQCVAwUQ -MzmhkfUVW/uOVC1dAQG3+AP/T1HL/5EYF0ij0yQmNTzt1cLt0b1e3N3zN/wPFFWs -BfrQ+nsv1zw7cEgxLtktk73wBGM9jUIdJu8phgLtl5a0m9UjBq5oxrJaNJr6UTxN -a+sFkapTLT1g84UFUO/+8qRB12v+hZr2WeXMYjHAFUT18mp3xwjW9DUV+2fW1Wag -YDKJAJUDBRAzOYK1s1pi61mfMj0BARBbA/930CHswOF0HIr+4YYUs1ejDnZ2J3zn -icTZhl9uAfEQq++Xor1x476j67Z9fESxyHltUxCmwxsJ1uOJRwzjyEoMlyFrIN4C -dE0C8g8BF+sRTt7VLURLERvlBvFrVZueXSnXvmMoWFnqpSpt3EmN6TNaLe8Cm87a -k6EvQy0dpnkPKokAlQMFEDD9Lorccp7v9qj1YQEBrRUD/3N4cCMWjzsIFp2Vh9y+ -RzUrblyF84tJyA7Rr1p+A7dxf7je3Zx5QMEXosWL1WGnS5vC9YH2WZwv6sCU61gU -rSy9z8KHlBEHh+Z6fdRMrjd9byPf+n3cktT0NhS23oXB1ZhNZcB2KKhVPlNctMqO -3gTYx+Nlo6xqjR+J2NnBYU8p -=7fQV ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - </sect1> - - <sect1> - <title>Core Team members</title> - - <sect2> - <title>&a.asami;</title> - - <programlisting> -Satoshi Asami <asami@cs.berkeley.edu> - aka <asami@FreeBSD.org> -Fingerprint = EB 3C 68 9E FB 6C EB 3F DB 2E 0F 10 8F CE 79 CA - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzPVyoQAAAEEAL7W+kipxB171Z4SVyyL9skaA7hG3eRsSOWk7lfvfUBLtPog -f3OKwrApoc/jwLf4+Qpdzv5DLEt/6Hd/clskhJ+q1gMNHyZ5ABmUxrTRRNvJMTrb -3fPU3oZj7sL/MyiFaT1zF8EaMP/iS2ZtcFsbYOqGeA8E/58uk4NA0SoeCNiJAAUR -tCVTYXRvc2hpIEFzYW1pIDxhc2FtaUBjcy5iZXJrZWxleS5lZHU+iQCVAwUQM/AT -+EqGN2HYnOMZAQF11QP/eSXb2FuTb1yX5yoo1Im8YnIk1SEgCGbyEbOMMBznVNDy -5g2TAD0ofLxPxy5Vodjg8rf+lfMVtO5amUH6aNcORXRncE83T10JmeM6JEp0T6jw -zOHKz8jRzygYLBayGsNIJ4BGxa4LeaGxJpO1ZEvRlNkPH/YEXK5oQmq9/DlrtYOJ -AEUDBRAz42JT8ng6GBbVvu0BAU8nAYCsJ8PiJpRUGlrz6rxjX8hqM1v3vqFHLcG+ -G52nVMBSy+RZBgzsYIPwI5EZtWAKb22JAJUDBRAz4QBWdbtuOHaj97EBAaQPA/46 -+NLUp+Wubl90JoonoXocwAg88tvAUVSzsxPXj0lvypAiSI2AJKsmn+5PuQ+/IoQy -lywRsxiQ5GD7C72SZ1yw2WI9DWFeAi+qa4b8n9fcLYrnHpyCY+zxEpu4pam8FJ7H -JocEUZz5HRoKKOLHErzXDiuTkkm72b1glmCqAQvnB4kAlQMFEDPZ3gyDQNEqHgjY -iQEBFfUEALu2C0uo+1Z7C5+xshWRYY5xNCzK20O6bANVJ+CO2fih96KhwsMof3lw -fDso5HJSwgFd8WT/sR+Wwzz6BAE5UtgsQq5GcsdYQuGI1yIlCYUpDp5sgswNm+OA -bX5a+r4F/ZJqrqT1J56Mer0VVsNfe5nIRsjd/rnFAFVfjcQtaQmjiQCVAwUQM9uV -mcdm8Q+/vPRJAQELHgP9GqNiMpLQlZig17fDnCJ73P0e5t/hRLFehZDlmEI2TK7j -Yeqbw078nZgyyuljZ7YsbstRIsWVCxobX5eH1kX+hIxuUqCAkCsWUY4abG89kHJr -XGQn6X1CX7xbZ+b6b9jLK+bJKFcLSfyqR3M2eCyscSiZYkWKQ5l3FYvbUzkeb6K0 -IVNhdG9zaGkgQXNhbWkgPGFzYW1pQEZyZWVCU0QuT1JHPg== -=39SC ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.jmb;</title> - - <programlisting> -Jonathan M. Bresler <jmb@FreeBSD.org> -f16 Fingerprint16 = 31 57 41 56 06 C1 40 13 C5 1C E3 E5 DC 62 0E FB - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQCNAzG2GToAAAEEANI6+4SJAAgBpl53XcfEr1M9wZyBqC0tzpie7Zm4vhv3hO8s -o5BizSbcJheQimQiZAY4OnlrCpPxijMFSaihshs/VMAz1qbisUYAMqwGEO/T4QIB -nWNo0Q/qOniLMxUrxS1RpeW5vbghErHBKUX9GVhxbiVfbwc4wAHbXdKX5jjdAAUR -tCVKb25hdGhhbiBNLiBCcmVzbGVyIDxqbWJARnJlZUJTRC5PUkc+iQCVAwUQNbtI -gAHbXdKX5jjdAQHamQP+OQr10QRknamIPmuHmFYJZ0jU9XPIvTTMuOiUYLcXlTdn -GyTUuzhbEywgtOldW2V5iA8platXThtqC68NsnN/xQfHA5xmFXVbayNKn8H5stDY -2s/4+CZ06mmJfqYmONF1RCbUk/M84rVT3Gn2tydsxFh4Pm32lf4WREZWRiLqmw+J -AJUDBRA0DfF99RVb+45ULV0BAcZ0BACCydiSUG1VR0a5DBcHdtin2iZMPsJUPRqJ -tWvP6VeI8OFpNWQ4LW6ETAvn35HxV2kCcQMyht1kMD+KEJz7r8Vb94TS7KtZnNvk -2D1XUx8Locj6xel5c/Lnzlnnp7Bp1XbJj2u/NzCaZQ0eYBdP/k7RLYBYHQQln5x7 -BOuiRJNVU4kAlQMFEDQLcShVLh4uc9KIpQEBJv4D/3mDrD0MM9EYOVuyXik3UGVI -8quYNA9ErVcLdt10NjYc16VI2HOnYVgPRag3Wt7W8wlXShpokfC/vCNt7f5JgRf8 -h2a1/MjQxtlD+4/Js8k7GLa53oLon6YQYk32IEKexoLPwIRO4L2BHWa3GzHJJSP2 -aTR/Ep90/pLdAOu/oJDUiQCVAwUQMqyL0LNaYutZnzI9AQF25QP9GFXhBrz2tiWz -2+0gWbpcGNnyZbfsVjF6ojGDdmsjJMyWCGw49XR/vPKYIJY9EYo4t49GIajRkISQ -NNiIz22fBAjT2uY9YlvnTJ9NJleMfHr4dybo7oEKYMWWijQzGjqf2m8wf9OaaofE -KwBX6nxcRbKsxm/BVLKczGYl3XtjkcuJAJUDBRA1ol5TZWCprDT5+dUBATzXA/9h -/ZUuhoRKTWViaistGJfWi26FB/Km5nDQBr/Erw3XksQCMwTLyEugg6dahQ1u9Y5E -5tKPxbB69eF+7JXVHE/z3zizR6VL3sdRx74TPacPsdhZRjChEQc0htLLYAPkJrFP -VAzAlSlm7qd+MXf8fJovQs6xPtZJXukQukPNlhqZ94kAPwMFEDSH/kF4tXKgazlt -bxECfk4AoO+VaFVfguUkWX10pPSSfvPyPKqiAJ4xn8RSIe1ttmnqkkDMhLh00mKj -lLQuSm9uYXRoYW4gTS4gQnJlc2xlciA8Sm9uYXRoYW4uQnJlc2xlckBVU2kubmV0 -PokAlQMFEDXbdSkB213Sl+Y43QEBV/4D/RLJNTrtAqJ1ATxXWv9g8Cr3/YF0GTmx -5dIrJOpBup7eSSmiM/BL9Is4YMsoVbXCI/8TqA67TMICvq35PZU4wboQB8DqBAr+ -gQ8578M7Ekw1OAF6JXY6AF2P8k7hMcVBcVOACELPT/NyPNByG5QRDoNmlsokJaWU -/2ls4QSBZZlb -=zbCw ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.ache;</title> - - <programlisting> -Andrey A. Chernov <ache@FreeBSD.org> - aka <ache@nagual.pp.ru> -Key fingerprint = 33 03 9F 48 33 7B 4A 15 63 48 88 0A C4 97 FD 49 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAiqUMGQAAAEEAPGhcD6A2Buey5LYz0sphDLpVgOZc/bb9UHAbaGKUAGXmafs -Dcb2HnsuYGgX/zrQXuCi/wIGtXcZWB97APtKOhFsZnPinDR5n/dde/mw9FnuhwqD -m+rKSL1HlN0z/Msa5y7g16760wHhSR6NoBSEG5wQAHIMMq7Q0uJgpPLZnQjrAAUT -tCVBbmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuYWd1YWwucHAucnU+iQCVAwUQM2Ez -u+JgpPLZnQjrAQEyugP8DPnS8ixJ5OeuYgPFQf5sy6l+LrB6hyaS+lgsUPahWjNY -cnaDmfda/q/BV5d4+y5rlQe/pjnYG7/yQuAR3jhlXz8XDrqlBOnW9AtYjDt5rMfJ -aGFTGXAPGZ6k6zQZE0/YurT8ia3qjvuZm3Fw4NJrHRx7ETHRvVJDvxA6Ggsvmr20 -JEFuZHJleSBBLiBDaGVybm92IDxhY2hlQEZyZWVCU0Qub3JnPokAlQMFEDR5uVbi -YKTy2Z0I6wEBLgED/2mn+hw4/3peLx0Sb9LNx//NfCCkVefSf2G9Qwhx6dvwbX7h -mFca97h7BQN4GubU1Z5Ffs6TeamSBrotBYGmOCwvJ6S9WigF9YHQIQ3B4LEjskAt -pcjU583y42zM11kkvEuQU2Gde61daIylJyOxsgpjSWpkxq50fgY2kLMfgl/ftCZB -bmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuaWV0enNjaGUubmV0PokAlQMFEDR5svDi -YKTy2Z0I6wEBOTQD/0OTCAXIjuak363mjERvzSkVsNtIH9hA1l0w6Z95+iH0fHrW -xXKT0vBZE0y0Em+S3cotLL0bMmVE3F3D3GyxhBVmgzjyx0NYNoiQjYdi+6g/PV30 -Cn4vOO6hBBpSyI6vY6qGNqcsawuRtHNvK/53MpOfKwSlICEBYQimcZhkci+EtCJB -bmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuYWd1YWwucnU+iQCVAwUQMcm5HeJgpPLZ -nQjrAQHwvQP9GdmAf1gdcuayHEgNkc11macPH11cwWjYjzA2YoecFMGV7iqKK8QY -rr1MjbGXf8DAG8Ubfm0QbI8Lj8iG3NgqIru0c72UuHGSn/APfGGG0AtPX5UK/k7B -gI0Ca2po6NA5nrSp8tDsdEz/4gyea84RXl2prtTf5Jj07hflbRstGXK0MkFuZHJl -eSBBLiBDaGVybm92LCBCbGFjayBNYWdlIDxhY2hlQGFzdHJhbC5tc2suc3U+iQCV -AwUQMCsAo5/rGryoL8h3AQHq1QQAidyNFqA9hvrmMcjpY7csJVFlGvj574Wj4GPa -o3pZeuQaMBmsWqaXLYnWU/Aldb6kTz6+nRcQX50zFH0THSPfApwEW7yybSTI5apJ -mWT3qhKN2vmLNg2yNzhqLTzHLD1lH3i1pfQq8WevrNfjLUco5S/VuekTma/osnzC -Cw7fQzCJAJUDBRAwKvwoa1pnjYGyp3kBARihBACoXr3qfG65hFCyKJISmjOvaoGr -anxUIkeDS0yQdTHzhQ+dwB1OhhK15E0Nwr0MKajLMm90n6+Zdb5y/FIjpPriu8dI -rlHrWZlewa88eEDM+Q/NxT1iYg+HaKDAE171jmLpSpCL0MiJtO0i36L3ekVD7Hv8 -vffOZHPSHirIzJOZTYkAlQMFEDAau6zFLUdtDb+QbQEBQX8D/AxwkYeFaYxZYMFO -DHIvSk23hAsjCmUA2Uil1FeWAusb+o8xRfPDc7TnosrIifJqbF5+fcHCG5VSTGlh -Bhd18YWUeabf/h9O2BsQX55yWRuB2x3diJ1xI/VVdG+rxlMCmE4ZR1Tl9x+Mtun9 -KqKVpB39VlkCBYQ3hlgNt/TJUY4riQCVAwUQMBHMmyJRltlmbQBRAQFQkwP/YC3a -hs3ZMMoriOlt3ZxGNUUPTF7rIER3j+c7mqGG46dEnDB5sUrkzacpoLX5sj1tGR3b -vz9a4vmk1Av3KFNNvrZZ3/BZFGpq3mCTiAC9zsyNYQ8L0AfGIUO5goCIjqwOTNQI -AOpNsJ5S+nMAkQB4YmmNlI6GTb3D18zfhPZ6uciJAJUCBRAwD0sl4uW74fteFRkB -AWsAA/9NYqBRBKbmltQDpyK4+jBAYjkXBJmARFXKJYTlnTgOHMpZqoVyW96xnaa5 -MzxEiu7ZWm5oL10QDIp1krkBP2KcmvfSMMHb5aGCCQc2/P8NlfXAuHtNGzYiI0UA -Iwi8ih/S1liVfvnqF9uV3d3koE7VsQ9OA4Qo0ZL2ggW+/gEaYIkAlQMFEDAOz6qx -/IyHe3rl4QEBIvYD/jIr8Xqo/2I5gncghSeFR01n0vELFIvaF4cHofGzyzBpYsfA -+6pgFI1IM+LUF3kbUkAY/2uSf9U5ECcaMCTWCwVgJVO+oG075SHEM4buhrzutZiM -1dTyTaepaPpTyRMUUx9ZMMYJs7sbqLId1eDwrJxUPhrBNvf/w2W2sYHSY8cdiQCV -AwUQMAzqgHcdkq6JcsfBAQGTxwQAtgeLFi2rhSOdllpDXUwz+SS6bEjFTWgRsWFM -y9QnOcqryw7LyuFmWein4jasjY033JsODfWQPiPVNA3UEnXVg9+n8AvNMPO8JkRv -Cn1eNg0VaJy9J368uArio93agd2Yf/R5r+QEuPjIssVk8hdcy/luEhSiXWf6bLMV -HEA0J+OJAJUDBRAwDUi+4mCk8tmdCOsBAatBBACHB+qtW880seRCDZLjl/bT1b14 -5po60U7u6a3PEBkY0NA72tWDQuRPF/Cn/0+VdFNxQUsgkrbwaJWOoi0KQsvlOm3R -rsxKbn9uvEKLxExyKH3pxp76kvz/lEWwEeKvBK+84Pb1lzpG3W7u2XDfi3VQPTi3 -5SZMAHc6C0Ct/mjNlYkAlQMFEDAMrPD7wj+NsTMUOQEBJckD/ik4WsZzm2qOx9Fw -erGq7Zwchc+Jq1YeN5PxpzqSf4AG7+7dFIn+oe6X2FcIzgbYY+IfmgJIHEVjDHH5 -+uAXyb6l4iKc89eQawO3t88pfHLJWbTzmnvgz2cMrxt94HRvgkHfvcpGEgbyldq6 -EB33OunazFcfZFRIcXk1sfyLDvYE -=1ahV ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.jkh;</title> - - <programlisting> -Jordan K. Hubbard <jkh@FreeBSD.org> -Fingerprint = 3C F2 27 7E 4A 6C 09 0A 4B C9 47 CD 4F 4D 0B 20 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzFjX0IAAAEEAML+nm9/kDNPp43ZUZGjYkm2QLtoC1Wxr8JulZXqk7qmhYcQ -jvX+fyoriJ6/7ZlnLe2oG5j9tZOnRLPvMaz0g9CpW6Dz3nkXrNPkmOFV9B8D94Mk -tyFeRJFqnkCuqBj6D+H8FtBwEeeTecSh2tJ0bZZTXnAMhxeOdvUVW/uOVC1dAAUR -tCNKb3JkYW4gSy4gSHViYmFyZCA8amtoQEZyZWVCU0Qub3JnPokBFQMFEDXCTXQM -j46yp4IfPQEBwO8IAIN0J09AXBf86dFUTFGcAMrEQqOF5IL+KGorAjzuYxERhKfD -ZV7jA+sCQqxkWfcVcE20kVyVYqzZIkio9a5zXP6TwA247JkPt54S1PmMDYHNlRIY -laXlNoji+4q3HP2DfHqXRT2859rYpm/fG/v6pWkos5voPKcZ2OFEp9W+Ap88oqw+ -5rx4VetZNJq1Epmis4INj6XqNqj85+MOOIYE+f445ohDM6B/Mxazd6cHFGGIR+az -VjZ6lCDMLjzhB5+FqfrDLYuMjqkMTR5z9DL+psUvPlCkYbQ11NEWtEmiIWjUcNJN -GCxGzv5bXk0XPu3ADwbPkFE2usW1cSM7AQFiwuyJAJUDBRAxe+Q9a1pnjYGyp3kB -AV7XA/oCSL/Cc2USpQ2ckwkGpyvIkYBPszIcabSNJAzm2hsU9Qa6WOPxD8olDddB -uJNiW/gznPC4NsQ0N8Zr4IqRX/TTDVf04WhLmd8AN9SOrVv2q0BKgU6fLuk979tJ -utrewH6PR2qBOjAaR0FJNk4pcYAHeT+e7KaKy96YFvWKIyDvc4kAlQMFEDF8ldof -f6kIA1j8vQEBDH4D/0Zm0oNlpXrAE1EOFrmp43HURHbij8n0Gra1w9sbfo4PV+/H -U8ojTdWLy6r0+prH7NODCkgtIQNpqLuqM8PF2pPtUJj9HwTmSqfaT/LMztfPA6PQ -csyT7xxdXl0+4xTDl1avGSJfYsI8XCAy85cTs+PQwuyzugE/iykJO1Bnj/paiQCV -AwUQMXvlBvUVW/uOVC1dAQF2fQP/RfYC6RrpFTZHjo2qsUHSRk0vmsYfwG5NHP5y -oQBMsaQJeSckN4n2JOgR4T75U4vS62aFxgPLJP3lOHkU2Vc7xhAuBvsbGr5RP8c5 -LvPOeUEyz6ZArp1KUHrtcM2iK1FBOmY4dOYphWyWMkDgYExabqlrAq7FKZftpq/C -BiMRuaw= -=C/Jw ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.phk;</title> - - <programlisting> -Poul-Henning Kamp <phk@FreeBSD.org> -Fingerprint = A3 F3 88 28 2F 9B 99 A2 49 F4 E2 FA 5A 78 8B 3E - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzAdpMIAAAEEALHDgrFUwhZtb7PbXg3upELoDVEUPFRwnmpJH1rRqyROUGcI -ooVe7u+FQlIs5OsXK8ECs/5Wpe2UrZSzHvjwBYOND5H42YtI5UULZLRCo5bFfTVA -K9Rpo5icfTsYihrzU2nmnycwFMk+jYXyT/ZDYWDP/BM9iLjj0x9/qQgDWPy9AAUR -tCNQb3VsLUhlbm5pbmcgS2FtcCA8cGhrQEZyZWVCU0Qub3JnPokAlQMFEDQQ0aZ1 -u244dqP3sQEBu4ID/jXFFeJgs2MdTDNOZM/FbfDhI4qxAbYUsqS3+Ra16yd8Wd/A -jV+IHJE2NomFWl8UrUjCGinXiwzPgK1OfFJrS9Og1wQLvAl0X84BA8MTP9BQr4w7 -6I/RbksgUSrVCIO8MJwlydjSPocWGBeXlVjbZxXzyuJk7H+TG+zuI5BuBcNIiQCV -AwUQMwYr2rNaYutZnzI9AQHiIQP/XxtBWFXaBRgVLEhRNpS07YdU+LsZGlLOZehN -9L4UnJFHQQPNOpMey2gF7Y95aBOw5/1xS5vlQpwmRFCntWsm/gqdzK6rulfr1r5A -y94LO5TAC6ucNu396Y4vo1TyD1STnRC466KlvmtQtAtFGgXlORWLL9URLzcRFd1h -D0yXd9aJAJUDBRAxfo19a1pnjYGyp3kBAQqyA/4v64vP3l1F0Sadn6ias761hkz/ -SMdTuLzILmofSCC4o4KWMjiWJHs2Soo41QlZi1+xMHzV32JKiwFlGtPHqL+EHyXy -Q4H3vmf9/1KF+0XCaMtgI0wWUMziPSTJK8xXbRRmMDK/0F4TnVVaUhnmf+h5K7O6 -XdmejDTa0X/NWcicmIkAlQMFEDF8lef1FVv7jlQtXQEBcnwD/0ro1PpUtlkLmreD -tsGTkNa7MFLegrYRvDDrHOwPZH152W2jPUncY+eArQJakeHiTDmJNpFagLZglhE0 -bqJyca+UwCXX+6upAclWHEBMg2byiWMMqyPVEEnpUoHM1sIkgdNWlfQAmipRBfYh -2LyCgWvR8CbtwPYIFvUmGgB3MR87iQCVAwUQMUseXB9/qQgDWPy9AQGPkwP/WEDy -El2Gkvua9COtMAifot2vTwuvWWpNopIEx0Ivey4aVbRLD90gGCJw8OGDEtqFPcNV -8aIiy3fYVKXGZZjvCKd7zRfhNmQn0eLDcymq2OX3aPrMc2rRlkT4Jx425ukR1gsO -qiQAgw91aWhY8dlw/EKzk8ojm52x4VgXaBACMjaJAJUDBRAxOUOg72G56RHVjtUB -AbL4A/9HOn5Qa0lq9tKI/HkSdc5fGQD/66VdCBAb292RbB7CS/EM07MdbcqRRYIa -0+0gwQ3OdsWPdCVgH5RIhp/WiC+UPkR1cY8N9Mg2kTwJfZZfNqN+BgWlgRMPN27C -OhYNl8Q33Nl9CpBLrZWABF44jPeT0EvvTzP/5ZQ7T75EsYKYiYkAlQMFEDDmryQA -8tkJ67sbQQEBPdsEALCj6v1OBuJLLJTlxmmrkqAZPVzt5QdeO3Eqa2tcPWcU0nqP -vHYMzZcZ7oFg58NZsWrhSQQDIB5e+K65Q/h6dC7W/aDskZd64jxtEznX2kt0/MOr -8OdsDis1K2f9KQftrAx81KmVwW4Tqtzl7NWTDXt44fMOtibCwVq8v2DFkTJy -=JKbP ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.rich;</title> - - <programlisting> -Rich Murphey <rich@FreeBSD.org> -fingerprint = AF A0 60 C4 84 D6 0C 73 D1 EF C0 E9 9D 21 DB E4 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAy97V+MAAAEEALiNM3FCwm3qrCe81E20UOSlNclOWfZHNAyOyj1ahHeINvo1 -FBF2Gd5Lbj0y8SLMno5yJ6P4F4r+x3jwHZrzAIwMs/lxDXRtB0VeVWnlj6a3Rezs -wbfaTeSVyh5JohEcKdoYiMG5wjATOwK/NAwIPthB1RzRjnEeer3HI3ZYNEOpAAUR -tCRSaWNoIE11cnBoZXkgPHJpY2hAbGFtcHJleS51dG1iLmVkdT6JAJUDBRAve15W -vccjdlg0Q6kBAZTZBACcNd/LiVnMFURPrO4pVRn1sVQeokVX7izeWQ7siE31Iy7g -Sb97WRLEYDi686osaGfsuKNA87Rm+q5F+jxeUV4w4szoqp60gGvCbD0KCB2hWraP -/2s2qdVAxhfcoTin/Qp1ZWvXxFF7imGA/IjYIfB42VkaRYu6BwLEm3YAGfGcSw== -=QoiM ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.jdp;</title> - - <programlisting> -John D. Polstra <jdp@polstra.com> -Fingerprint = 54 3A 90 59 6B A4 9D 61 BF 1D 03 09 35 8D F6 0D - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzMElMEAAAEEALizp6ZW9QifQgWoFmG3cXhzQ1+Gt+a4S1adC/TdHdBvw1M/ -I6Ok7TC0dKF8blW3VRgeHo4F3XhGn+n9MqIdboh4HJC5Iiy63m98sVLJSwyGO4oM -dkEGyyCLxqP6h/DU/tzNBdqFzetGtYvU4ftt3RO0a506cr2CHcdm8Q+/vPRJAAUR -tCFKb2huIEQuIFBvbHN0cmEgPGpkcEBwb2xzdHJhLmNvbT6JAJUDBRAzBNBE9RVb -+45ULV0BAWgiA/0WWO3+c3qlptPCHJ3DFm6gG/qNKsY94agL/mHOr0fxMP5l2qKX -O6a1bWkvGoYq0EwoKGFfn0QeHiCl6jVi3CdBX+W7bObMcoi+foqZ6zluOWBC1Jdk -WQ5/DeqQGYXqbYjqO8voCScTAPge3XlMwVpMZTv24u+nYxtLkE0ZcwtY9IkAlQMF -EDMEt/DHZvEPv7z0SQEBXh8D/2egM5ckIRpGz9kcFTDClgdWWtlgwC1iI2p9gEhq -aufy+FUJlZS4GSQLWB0BlrTmDC9HuyQ+KZqKFRbVZLyzkH7WFs4zDmwQryLV5wkN -C4BRRBXZfWy8s4+zT2WQD1aPO+ZsgRauYLkJgTvXTPU2JCN62Nsd8R7bJS5tuHEm -7HGmiQCVAwUQMwSvHB9/qQgDWPy9AQFAhAQAgJ1AlbKITrEoJ0+pLIsov3eQ348m -SVHEBGIkU3Xznjr8NzT9aYtq4TIzt8jplqP3QoV1ka1yYpZf0NjvfZ+ffYp/sIaU -wPbEpgtmHnVWJAebMbNs/Ad1w8GDvxEt9IaCbMJGZnHmfnEqOBIxF7VBDPHHoJxM -V31K/PIoYsHAy5w= -=cHFa ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.guido;</title> - - <programlisting> -Guido van Rooij <guido@gvr.win.tue.nl> -Fingerprint = 16 79 09 F3 C0 E4 28 A7 32 62 FA F6 60 31 C0 ED - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzGeO84AAAEEAKKAY91Na//DXwlUusr9GVESSlVwVP6DyH1wcZXhfN1fyZHq -SwhMCEdHYoojQds+VqD1iiZQvv1RLByBgj622PDAPN4+Z49HjGs7YbZsUNuQqPPU -wRPpP6ty69x1hPKq1sQIB5MS4radpCM+4wbZbhxv7l4rP3RWUbNaYutZnzI9AAUR -tCZHdWlkbyB2YW4gUm9vaWogPGd1aWRvQGd2ci53aW4udHVlLm5sPokAlQMFEDMG -Hcgff6kIA1j8vQEBbYgD/jm9xHuUuY+iXDkOzpCXBYACYEZDV913MjtyBAmaVqYo -Rh5HFimkGXe+rCo78Aau0hc57fFMTsJqnuWEqVt3GRq28hSK1FOZ7ni9/XibHcmN -rt2yugl3hYpClijo4nrDL1NxibbamkGW/vFGcljS0jqXz6NDVbGx5Oo7HBByxByz -iQCVAwUQMhmtVjt/x7zOdmsfAQFuVQQApsVUTigT5YWjQA9Nd5Z0+a/oVtZpyw5Z -OljLJP3vqJdMa6TidhfcatjHbFTve5x1dmjFgMX/MQTd8zf/+Xccy/PX4+lnKNpP -eSf1Y4aK+E8KHmBGd6GzX6CIboyGYLS9e3kGnN06F2AQtaLyJFgQ71wRaGuyKmQG -FwTn7jiKb1aJAJUDBRAyEOLXPt3iN6QQUSEBATwQA/9jqu0Nbk154+Pn+9mJX/YT -fYR2UqK/5FKCqgL5Nt/Deg2re0zMD1f8F9Dj6vuAAxq8hnOkIHKlWolMjkRKkzJi -mSPEWl3AuHJ31k948J8it4f8kq/o44usIA2KKVMlI63Q/rmNdfWCyiYQEVGcRbTm -GTdZIHYCOgV5dOo4ebFqgYkAlQMFEDIE1nMEJn15jgpJ0QEBW6kEAKqN8XSgzTqf -CrxFXT07MlHhfdbKUTNUoboxCGCLNW05vf1A8F5fdE5i14LiwkldWIzPxWD+Sa3L -fNPCfCZTaCiyGcLyTzVfBHA18MBAOOX6JiTpdcm22jLGUWBf/aJK3yz/nfbWntd/ -LRHysIdVp29lP5BF+J9/Lzbb/9LxP1taiQCVAwUQMgRXZ44CzbsJWQz9AQFf7gP/ -Qa2FS5S6RYKG3rYanWADVe/ikFV2lxuM1azlWbsmljXvKVWGe6cV693nS5lGGAjx -lbd2ADwXjlkNhv45HLWFm9PEveO9Jjr6tMuXVt8N2pxiX+1PLUN9CtphTIU7Yfjn -s6ryZZfwGHSfIxNGi5ua2SoXhg0svaYnxHxXmOtH24iJAJUDBRAyAkpV8qaAEa3W -TBkBARfQBAC+S3kbulEAN3SI7/A+A/dtl9DfZezT9C4SRBGsl2clQFMGIXmMQ/7v -7lLXrKQ7U2zVbgNfU8smw5h2vBIL6f1PyexSmc3mz9JY4er8KeZpcf6H0rSkHl+i -d7TF0GvuTdNPFO8hc9En+GG6QHOqbkB4NRZ6cwtfwUMhk2FHXBnjF4kAlQMFEDH5 -FFukUJAsCdPmTQEBe74EAMBsxDnbD9cuI5MfF/QeTNEG4BIVUZtAkDme4Eg7zvsP -d3DeJKCGeNjiCWYrRTCGwaCWzMQk+/+MOmdkI6Oml+AIurJLoHceHS9jP1izdP7f -N2jkdeJSBsixunbQWtUElSgOQQ4iF5kqwBhxtOfEP/L9QsoydRMR1yB6WPD75H7V -iQCVAwUQMZ9YNGtaZ42Bsqd5AQH0PAQAhpVlAc3ZM/KOTywBSh8zWKVlSk3q/zGn -k7hJmFThnlhH1723+WmXE8aAPJi+VXOWJUFQgwELJ6R8jSU2qvk2m1VWyYSqRKvc -VRQMqT2wjss0GE1Ngg7tMrkRHT0il7E2xxIb8vMrIwmdkbTfYqBUhhGnsWPHZHq7 -MoA1/b+rK7CJAJUDBRAxnvXh3IDyptUyfLkBAYTDA/4mEKlIP/EUX2Zmxgrd/JQB -hqcQlkTrBAaDOnOqe/4oewMKR7yaMpztYhJs97i03Vu3fgoLhDspE55ooEeHj0r4 -cOdiWfYDsjSFUYSPNVhW4OSruMA3c29ynMqNHD7hpr3rcCPUi7J2RncocOcCjjK2 -BQb/9IAUNeK4C9gPxMEZLokAlQMFEDGeO86zWmLrWZ8yPQEBEEID/2fPEUrSX3Yk -j5TJPFZ9MNX0lEo7AHYjnJgEbNI4pYm6C3PnMlsYfCSQDHuXmRQHAOWSdwOLvCkN -F8eDaF3M6u0urgeVJ+KVUnTz2+LZoZs12XSZKCte0HxjbvPpWMTTrYyimGezH79C -mgDVjsHaYOx3EXF0nnDmtXurGioEmW1J -=mSvM ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.peter;</title> - - <programlisting> -Peter Wemm <peter@FreeBSD.org> - aka <peter@spinner.dialix.com> - aka <peter@haywire.dialix.com> - aka <peter@perth.dialix.oz.au> -Key fingerprint = 47 05 04 CA 4C EE F8 93 F6 DB 02 92 6D F5 58 8A - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAy9/FJwAAAEEALxs9dE9tFd0Ru1TXdq301KfEoe5uYKKuldHRBOacG2Wny6/ -W3Ill57hOi2+xmq5X/mHkapywxvy4cyLdt31i4GEKDvxpDvEzAYcy2n9dIup/eg2 -kEhRBX9G5k/LKM4NQsRIieaIEGGgCZRm0lINqw495aZYrPpO4EqGN2HYnOMZAAUT -tCVQZXRlciBXZW1tIDxwZXRlckBoYXl3aXJlLmRpYWxpeC5jb20+iQCVAwUQMwWT -cXW7bjh2o/exAQEFkQP+LIx5zKlYp1uR24xGApMFNrNtjh+iDIWnxxb2M2Kb6x4G -9z6OmbUCoDTGrX9SSL2Usm2RD0BZfyv9D9QRWC2TSOPkPRqQgIycc11vgbLolJJN -eixqsxlFeKLGEx9eRQCCbo3dQIUjc2yaOe484QamhsK1nL5xpoNWI1P9zIOpDiGJ -AJUDBRAxsRPqSoY3Ydic4xkBAbWLA/9q1Fdnnk4unpGQsG31Qbtr4AzaQD5m/JHI -4gRmSmbj6luJMgNG3fpO06Gd/Z7uxyCJB8pTst2a8C/ljOYZxWT+5uSzkQXeMi5c -YcI1sZbUpkHtmqPW623hr1PB3ZLA1TIcTbQW+NzJsxQ1Pc6XG9fGkT9WXQW3Xhet -AP+juVTAhLQlUGV0ZXIgV2VtbSA8cGV0ZXJAcGVydGguZGlhbGl4Lm96LmF1PokA -lQMFEDGxFCFKhjdh2JzjGQEB6XkD/2HOwfuFrnQUtdwFPUkgtEqNeSr64jQ3Maz8 -xgEtbaw/ym1PbhbCk311UWQq4+izZE2xktHTFClJfaMnxVIfboPyuiSF99KHiWnf -/Gspet0S7m/+RXIwZi1qSqvAanxMiA7kKgFSCmchzas8TQcyyXHtn/gl9v0khJkb -/fv3R20btB5QZXRlciBXZW1tIDxwZXRlckBGcmVlQlNELm9yZz6JAJUDBRAxsRJd -SoY3Ydic4xkBAZJUA/4i/NWHz5LIH/R4IF/3V3LleFyMFr5EPFY0/4mcv2v+ju9g -brOEM/xd4LlPrx1XqPeZ74JQ6K9mHR64RhKR7ZJJ9A+12yr5dVqihe911KyLKab9 -4qZUHYi36WQu2VtLGnw/t8Jg44fQSzbBF5q9iTzcfNOYhRkSD3BdDrC3llywO7Ql -UGV0ZXIgV2VtbSA8cGV0ZXJAc3Bpbm5lci5kaWFsaXguY29tPokAlQMFEDGxEi1K -hjdh2JzjGQEBdA4EAKmNFlj8RF9HQsoI3UabnvYqAWN5wCwEB4u+Zf8zq6OHic23 -TzoK1SPlmSdBE1dXXQGS6aiDkLT+xOdeewNs7nfUIcH/DBjSuklAOJzKliXPQW7E -kuKNwy4eq5bl+j3HB27i+WBXhn6OaNNQY674LGaR41EGq44Wo5ATcIicig/z -=gv+h ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.joerg;</title> - - <programlisting> -Type Bits/KeyID Date User ID -pub 1024/76A3F7B1 1996/04/27 Joerg Wunsch <joerg_wunsch@uriah.heep.sax.de> - Key fingerprint = DC 47 E6 E4 FF A6 E9 8F 93 21 E0 7D F9 12 D6 4E - Joerg Wunsch <joerg_wunsch@interface-business.de> - Joerg Wunsch <j@uriah.heep.sax.de> - Joerg Wunsch <j@interface-business.de> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzGCFeAAAAEEAKmRBU2Nvc7nZy1Ouid61HunA/5hF4O91cXm71/KPaT7dskz -q5sFXvPJPpawwvqHPHfEbAK42ZaywyFp59L1GaYj87Pda+PlAYRJyY2DJl5/7JPe -ziq+7B8MdvbX6D526sdmcR+jPXPbHznASjkx9DPmK+7TgFujyXW7bjh2o/exAAUR -tC1Kb2VyZyBXdW5zY2ggPGpvZXJnX3d1bnNjaEB1cmlhaC5oZWVwLnNheC5kZT6J -AJUDBRA0FFkBs1pi61mfMj0BAfDCA/oCfkjrhvRwRCpSL8klJ1YDoUJdmw+v4nJc -pw3OpYXbwKOPLClsE7K3KCQscHel7auf91nrekAwbrXv9Clp0TegYeAQNjw5vZ9f -L6UZ5l3fH8E2GGA7+kqgNWs1KxAnG5GdUvJ9viyrWm8dqWRGo+loDWlZ12L2OgAD -fp7jVZTI1okAlQMFEDQPrLoff6kIA1j8vQEB2XQEAK/+SsQPCT/X4RB/PBbxUr28 -GpGJMn3AafAaA3plYw3nb4ONbqEw9tJtofAn4UeGraiWw8nHYR2DAzoAjR6OzuX3 -TtUV+57BIzrTPHcNkb6h8fPuHU+dFzR+LNoPaGJsFeov6w+Ug6qS9wa5FGDAgaRo -LHSyBxcRVoCbOEaS5S5EiQCVAwUQM5BktWVgqaw0+fnVAQGKPwP+OiWho3Zm2GKp -lEjiZ5zx3y8upzb+r1Qutb08jr2Ewja04hLg0fCrt6Ad3DoVqxe4POghIpmHM4O4 -tcW92THQil70CLzfCxtfUc6eDzoP3krD1/Gwpm2hGrmYA9b/ez9+r2vKBbnUhPmC -glx5pf1IzHU9R2XyQz9Xu7FI2baOSZqJAJUDBRAyCIWZdbtuOHaj97EBAVMzA/41 -VIph36l+yO9WGKkEB+NYbYOz2W/kyi74kXLvLdTXcRYFaCSZORSsQKPGNMrPZUoL -oAKxE25AoCgl5towqr/sCcu0A0MMvJddUvlQ2T+ylSpGmWchqoXCN7FdGyxrZ5zz -xzLIvtcio6kaHd76XxyJpltCASupdD53nEtxnu8sRrQxSm9lcmcgV3Vuc2NoIDxq -b2VyZ193dW5zY2hAaW50ZXJmYWNlLWJ1c2luZXNzLmRlPokAlQMFEDIIhfR1u244 -dqP3sQEBWoID/RhBm+qtW+hu2fqAj9d8CVgEKJugrxZIpXuCKFvO+bCgQtogt9EX -+TJh4s8UUdcFkyEIu8CT2C3Rrr1grvckfxvrTgzSzvtYyv1072X3GkVY+SlUMBMA -rdl1qNW23oT7Q558ajnsaL065XJ5m7HacgTTikiofYG8i1s7TrsEeq6PtCJKb2Vy -ZyBXdW5zY2ggPGpAdXJpYWguaGVlcC5zYXguZGU+iQCVAwUQMaS91D4gHQUlG9CZ -AQGYOwQAhPpiobK3d/fz+jWrbQgjkoO+j39glYGXb22+6iuEprFRs/ufKYtjljNT -NK3B4DWSkyIPawcuO4Lotijp6jke2bsjFSSashGWcsJlpnwsv7EeFItT3oWTTTQQ -ItPbtNyLW6M6xB+jLGtaAvJqfOlzgO9BLfHuA2LY+WvbVW447SWJAJUDBRAxqWRs -dbtuOHaj97EBAXDBA/49rzZB5akkTSbt/gNd38OJgC+H8N5da25vV9dD3KoAvXfW -fw7OxIsxvQ/Ab+rJmukrrWxPdsC+1WU1+1rGa4PvJp/VJRDes2awGrn+iO7/cQoS -IVziC27JpcbvjLvLVcBIiy1yT/RvJ+87a3jPRHt3VFGcpFh4KykxxSNiyGygl4kA -lQMFEDGCUB31FVv7jlQtXQEB5KgD/iIJZe5lFkPr2B/Cr7BKMVBot1/JSu05NsHg -JZ3uK15w4mVtNPZcFi/dKbn+qRM6LKDFe/GF0HZD/ZD1FJt8yQjzF2w340B+F2GG -EOwnClqZDtEAqnIBzM/ECQQqH+6Bi8gpkFZrFgg5eON7ikqmusDnOlYStM/CBfgp -SbR8kDmFtCZKb2VyZyBXdW5zY2ggPGpAaW50ZXJmYWNlLWJ1c2luZXNzLmRlPokA -lQMFEDHioSdlYKmsNPn51QEByz8D/10uMrwP7MdaXnptd1XNFhpaAPYTVAOcaKlY -OGI/LLR9PiU3FbqXO+7INhaxFjBxa0Tw/p4au5Lq1+Mx81edHniJZNS8tz3I3goi -jIC3+jn2gnVAWnK5UZUTUVUn/JLVk/oSaIJNIMMDaw4J9xPVVkb+Fh1A+XqtPsVa -YESrNp0+iQCVAwUQMwXkzcdm8Q+/vPRJAQEA4QQAgNNX1HFgXrMetDb+w6yEGQDk -JCDAY9b6mA2HNeKLQAhsoZl4HwA1+iuQaCgo3lyFC+1Sf097OUTs74z5X1vCedqV -oFw9CxI3xuctt3pJCbbN68flOlnq0WdYouWWGlFwLlh5PEy//VtwX9lqgsizlhzi -t+fX6BT4BgKi5baDhrWJAJUDBRAyCKveD9eCJxX4hUkBAebMA/9mRPy6K6i7TX2R -jUKSl2p5oYrXPk12Zsw4ijuktslxzQhOCyMSCGK2UEC4UM9MXp1H1JZQxN/DcfnM -7VaUt+Ve0wZ6DC9gBSHJ1hKVxHe5XTj26mIr4rcXNy2XEDMK9QsnBxIAZnBVTjSO -LdhqqSMp3ULLOpBlRL2RYrqi27IXr4kAlQMFEDGpbnd1u244dqP3sQEBJnQD/RVS -Azgf4uorv3fpbosI0LE3LUufAYGBSJNJnskeKyudZkNkI5zGGDwVneH/cSkKT4OR -ooeqcTBxKeMaMuXPVl30QahgNwWjfuTvl5OZ8orsQGGWIn5FhqYXsKkjEGxIOBOf -vvlVQ0UbcR0N2+5F6Mb5GqrXZpIesn7jFJpkQKPU -=97h7 ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - </sect1> - - <sect1> - <title>Developers</title> - - <sect2> - <title>&a.wosch;</title> - - <programlisting> -Type Bits/KeyID Date User ID -pub 1024/2B7181AD 1997/08/09 Wolfram Schneider <wosch@FreeBSD.org> - Key fingerprint = CA 16 91 D9 75 33 F1 07 1B F0 B4 9F 3E 95 B6 09 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzPs+aEAAAEEAJqqMm2I9CxWMuHDvuVO/uh0QT0az5ByOktwYLxGXQmqPG1G -Q3hVuHWYs5Vfm/ARU9CRcVHFyqGQ3LepoRhDHk+JcASHan7ptdFsz7xk1iNNEoe0 -vE2rns38HIbiyQ/2OZd4XsyhFOFtExNoBuyDyNoe3HbHVBQT7TmN/mkrcYGtAAUR -tCVXb2xmcmFtIFNjaG5laWRlciA8d29zY2hARnJlZUJTRC5vcmc+iQCVAwUQNxnH -AzmN/mkrcYGtAQF5vgP/SLOiI4AwuPHGwUFkwWPRtRzYSySXqwaPCop5mVak27wk -pCxGdzoJO2UgcE812Jt92Qas91yTT0gsSvOVNATaf0TM3KnKg5ZXT1QIzYevWtuv -2ovAG4au3lwiFPDJstnNAPcgLF3OPni5RCUqBjpZFhb/8YDfWYsMcyn4IEaJKre0 -JFdvbGZyYW0gU2NobmVpZGVyIDxzY2huZWlkZXJAemliLmRlPokAlQMFEDcZxu85 -jf5pK3GBrQEBCRgD/jPj1Ogx4O769soiguL1XEHcxhqtrpKZkKwxmDLRa0kJFwLp -bBJ3Qz3vwaB7n5gQU0JiL1B2M7IxVeHbiIV5pKp7FD248sm+HZvBg6aSnCg2JPUh -sHd1tK5X4SB5cjFt3Cj0LIN9/c9EUxm3SoML9bovmze60DckErrRNOuTk1IntCJX -b2xmcmFtIFNjaG5laWRlciA8d29zY2hAYXBmZWwuZGU+iQEVAwUQNmfWXAjJLLJO -sC7dAQEASAgAnE4g2fwMmFkQy17ATivljEaDZN/m0GdXHctdZ8CaPrWk/9/PTNK+ -U6xCewqIKVwtqxVBMU1VpXUhWXfANWCB7a07D+2GrlB9JwO5NMFJ6g0WI/GCUXjC -xb3NTkNsvppL8Rdgc8wc4f23GG4CXVggdTD2oUjUH5Bl7afgOT4xLPAqePhS7hFB -UnMsbA94OfxPtHe5oqyaXt6cXH/SgphRhzPPZq0yjg0Ef+zfHVamvZ6Xl2aLZmSv -Cc/rb0ShYDYi39ly9OPPiBPGbSVw2Gg804qx3XAKiTFkLsbYQnRt7WuCPsOVjFkf -CbQS31TaclOyzenZdCAezubGIcrJAKZjMIkAlQMFEDPs+aE5jf5pK3GBrQEBlIAD -/3CRq6P0m1fi9fbPxnptuipnoFB/m3yF6IdhM8kSe4XlXcm7tS60gxQKZgBO3bDA -5QANcHdl41Vg95yBAZepPie6iQeAAoylRrONeIy6XShjx3S0WKmA4+C8kBTL+vwa -UqF9YJ1qesZQtsXlkWp/Z7N12RkueVAVQ7wRPwfnz6E3tC5Xb2xmcmFtIFNjaG5l -aWRlciA8d29zY2hAcGFua2UuZGUuZnJlZWJzZC5vcmc+iQCVAwUQNxnEqTmN/mkr -cYGtAQFnpQP9EpRZdG6oYN7d5abvIMN82Z9x71a4QBER+R62mU47wqdRG2b6jMMh -3k07b2oiprVuPhRw/GEPPQevb6RRT6SD9CPYAGfK3MDE8ZkMj4d+7cZDRJQ35sxv -gAzQwuA9l7kS0mt5jFRPcEg5/KpuyehRLckjx8jpEM7cEJDHXhBIuVg= -=3V1R ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.brian;</title> - - <programlisting> -Type Bits/KeyID Date User ID -pub 1024/666A7421 1997/04/30 Brian Somers <brian@awfulhak.org> - Key fingerprint = 2D 91 BD C2 94 2C 46 8F 8F 09 C4 FC AD 12 3B 21 - Brian Somers <brian@uk.FreeBSD.org> - Brian Somers <brian@OpenBSD.org> - Brian Somers <brian@FreeBSD.org> ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzNmogUAAAEEALdsjVsV2dzO8UU4EEo7z3nYuvB2Q6YJ8sBUYjB8/vfR5oZ9 -7aEQjgY5//pXvS30rHUB9ghk4kIFSljzeMudE0K2zH5n2sxpLbBKWZRDLS7xnrDC -I3j9CNKwQBzMPs0fUT46gp96nf1X8wPiJXkDUEia/c0bRbXlLw7tvOdmanQhAAUR -tCFCcmlhbiBTb21lcnMgPGJyaWFuQGF3ZnVsaGFrLm9yZz6JAJUDBRA3Fjs4H3+p -CANY/L0BAZOxBACTZ1zPdaJzEdT4AfrebQbaU4ytEeodnVXZIkc8Il+LDlDOUAIe -k5PgnHTRM4yiwcZuYQrCDRFgdOofcFfRo0PD7mGFzd22qPGmbvHiDBCYCyhlkPXW -IDeoA1cX77JlU1NFdy0dZwuX7csaMlpjCkOPc7+856mr6pQi48zj7yZtrYkAlQMF -EDcUqZ2dZ0EADG4SFQEBEm0EAL2bBNc4vpxPrg3ATdZ/PekpL6lYj3s9pBf8f7eY -LXq438A/ywiWkrL74gXxcZ2Ey9AHZW+rbJPzUbrfMAgP3uWobeSvDyKRo1wtKnTY -Hy+OEIbBIHDmIUuK3L7KupBf7WAI46Q7fnyz0txvtRruDjvfoyl9/TSRfIKcaw2a -INh7iQCVAwUQNwyWpmdKPfFUsXG5AQEIrAQAmukv2u9ihcnO2Zaak265I+gYozu+ -biAngdXNfhTGMeExFzdzQ8Qe7EJugMpIDEkJq2goY35sGitD+ogSVWECjcVbHIAP -M2u9axFGlK7fDOmmkH2ZWDMtwx2I5dZps3q2g9mY2O9Az5Yokp7GW7viSpWXHTRH -xOsuY6aze71U7RWJAHUDBRA3DAEvDuwDH3697LEBAWRHAv9XXkub6mir/DCxzKI2 -AE3tek40lRfU6Iukjl/uzT9GXcL3uEjIewiPTwN+k4IL+qcCEdv8WZgv/tO45r59 -IZQsicNaSAsKX/6Cxha6Hosg1jw4rjdyz13rgYRi/nreq5mJAJUDBRA2r0CM9p+f -Pnxlu7UBAYObA/40s5SwEpXTrePO78AoUFEa5Z4bgyxkpT7BVbq6m/oQtK509Xe2 -M2y0XTLkd86oXpjyKzGzWq8T6ZTKNdF9+5LhS2ylJytdPq1AjDk2BocffWX4+pXn -RPiC6XcNdYGiQL8OTHvZESYQDiHeMfwA8WdMzFK1R80nJMwANYXjJJrLzYkAlQMF -EDNt51zvs7EFZlNtbQEBW0UD/jZB6UDdEFdhS0hxgahv5CxaQDWQbIEpAY9JL1yg -d1RWMKUFGXdRkWZmHEA4NvtwFFeam/HZm4yuGf8yldMyo84loTcVib7lKh4CumGx -FT5Pxeh/F8u9EeQzclRFSMhVl0BA2/HEGyjw0kbkprI/RD3pXD7ewTAUrj2O3XhE -InLgiQCVAwUQM3O9vWyr6JZzEUkFAQF9nAP9Hco0V/3Kl70N5ryPVgh41nUTd7Td -6fUjx8yPoSZLX8vVZ8XMyd8ULFmzsmA+2QG4HcKo/x/4s50O3o8c+o1qSYj0Tp+K -4Z8lneMVlgBNdrRcq4ijEgk0qGqSlsXyLElkVPEXAADBVgzf6yqvipDwXNVzl6e3 -GPLE8U2TAnBFZX6JAJUDBRAzZqIFDu2852ZqdCEBATsuBACI3ofP7N3xuHSc7pWL -NsnFYVEc9utBaclcagxjLLzwPKzMBcLjNGyGXIZQNB0d4//UMUJcMS7vwZ8MIton -VubbnJVHuQvENloRRARtarF+LC7OLMCORrGtbt0FtYgvBaqtgXlNcKXD6hRT+ghR -bi3q34akA7Xw8tiFIxdVgSusALQjQnJpYW4gU29tZXJzIDxicmlhbkB1ay5GcmVl -QlNELm9yZz6JAJUDBRA3FLWcnWdBAAxuEhUBAcYYBACos9nKETuaH+z2h0Ws+IIY -mN9FEm8wpPUcQmX5GFhfBUQ+rJbflzv0jJ/f2ac9qJHgIIAlJ3pMkfMpU8UYHEuo -VCe4ZTU5sr4ZdBaF9kpm2OriFgZwIv4QAi7dCMu9ZwGRtZ3+z3DQsVSagucjZTIe -yTUR6K+7E3YXANQjOdqFZYkAlQMFEDcUpeQO7bznZmp0IQEB4HED/Ru3NjwWO1gl -xEiLTzRpU31Rh1Izw1lhVMVJkLAGBw9ieSkjvdIkuhqV1i+W4wKBClT0UOE28Kjp -WbBKPFIASRYzN4ySwpprsG5H45EFQosovYG/HPcMzXU2GMj0iwVTxnMq7I8oH588 -ExHqfEN2ARD3ngmB2499ruyGl26pW/BftCBCcmlhbiBTb21lcnMgPGJyaWFuQE9w -ZW5CU0Qub3JnPokAlQMFEDcUtW6dZ0EADG4SFQEBQwsD/j9B/lkltIdnQdjOqR/b -dOBgJCtUf905y6kD+k4kbxeT1YAaA65KJ2o/Zj+i+69F2+BUJ/3kYB7prKwut2h0 -ek1ZtncGxoAsQdFJ5JSeMkwUZ5qtGeCmVPb59+KPq3nU6p3RI8Bn77FzK//Qy+IW -/WFVJbf/6NCNCbyRiRjPbGl/iQCVAwUQNxSlyA7tvOdmanQhAQFzMAP/dvtsj3yB -C+seiy6fB/nS+NnKBoff3Ekv57FsZraGt4z9n4sW61eywaiRzuKlhHqrDE17STKa -fBOaV1Ntl7js7og5IFPWNlVh1cK+spDmd655D8pyshziDF6fSAsqGfTn35xl23Xj -O20MMK44j4I5V6rEyUDBDrmX49J56OFkfwa0IEJyaWFuIFNvbWVycyA8YnJpYW5A -RnJlZUJTRC5vcmc+iQCVAwUQNxS1Y51nQQAMbhIVAQHPBQP+IMUlE4DtEvSZFtG4 -YK9usfHSkStIafh/F/JzSsqdceLZgwcuifbemw79Rhvqhp0Cyp7kuI2kHO3a19kZ -3ZXlDl3VDg41SV/Z5LzNw9vaZKuF/vtGaktOjac5E5aznWGIA5czwsRgydEOcd8O -VPMUMrdNWRI6XROtnbZaRSwmD8aJAJUDBRA3FKWuDu2852ZqdCEBAWVJA/4x3Mje -QKV+KQoO6mOyoIcD4GK1DjWDvNHGujJbFGBmARjr/PCm2cq42cPzBxnfRhCfyEvN -aesNB0NjLjRU/m7ziyVn92flAzHqqmU36aEdqooXUY2T3vOYzo+bM7VtInarG1iU -qw1G19GgXUwUkPvy9+dNIM/aYoI/e0Iv3P9uug== -=R3k0 ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/policies/chapter.sgml b/en/handbook/policies/chapter.sgml deleted file mode 100644 index 83cf490b8a..0000000000 --- a/en/handbook/policies/chapter.sgml +++ /dev/null @@ -1,391 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.9 1999-07-28 20:23:31 nik Exp $ ---> - -<chapter id="policies"> - <title>Source Tree Guidelines and Policies</title> - - <para><emphasis>Contributed by &a.phk;.</emphasis></para> - - <para>This chapter documents various guidelines and policies in force for - the FreeBSD source tree.</para> - - <sect1 id="policies-maintainer"> - <title><makevar>MAINTAINER</makevar> on Makefiles</title> - - <para>June 1996.</para> - - <para>If a particular portion of the FreeBSD distribution is being - maintained by a person or group of persons, they can communicate this - fact to the world by adding a - - <programlisting> -MAINTAINER= email-addresses</programlisting> - - line to the <filename>Makefile</filename>s covering this portion of the - source tree.</para> - - <para>The semantics of this are as follows:</para> - - <para>The maintainer owns and is responsible for that code. This means - that he is responsible for fixing bugs and answer problem reports - pertaining to that piece of the code, and in the case of contributed - software, for tracking new versions, as appropriate.</para> - - <para>Changes to directories which have a maintainer defined shall be sent - to the maintainer for review before being committed. Only if the - maintainer does not respond for an unacceptable period of time, to - several emails, will it be acceptable to commit changes without review - by the maintainer. However, it is suggested that you try and have the - changes reviewed by someone else if at all possible.</para> - - <para>It is of course not acceptable to add a person or group as - maintainer unless they agree to assume this duty. On the other hand it - doesn't have to be a committer and it can easily be a group of - people.</para> - </sect1> - - <sect1> - <title>Contributed Software</title> - - <para><emphasis>Contributed by &a.phk; and &a.obrien;. </emphasis></para> - - <para>June 1996.</para> - - <para>Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this <emphasis>contributed</emphasis> software. Some - examples are perl, gcc and patch.</para> - - <para>Over the last couple of years, various methods have been used in - dealing with this type of software and all have some number of - advantages and drawbacks. No clear winner has emerged.</para> - - <para>Since this is the case, after some debate one of these methods has - been selected as the “official” method and will be required - for future imports of software of this kind. Furthermore, it is - strongly suggested that existing contributed software converge on this - model over time, as it has significant advantages over the old method, - including the ability to easily obtain diffs relative to the - “official” versions of the source by everyone (even without - cvs access). This will make it significantly easier to return changes - to the primary developers of the contributed software.</para> - - <para>Ultimately, however, it comes down to the people actually doing the - work. If using this model is particularly unsuited to the package being - dealt with, exceptions to these rules may be granted only with the - approval of the core team and with the general consensus of the other - developers. The ability to maintain the package in the future will be a - key issue in the decisions.</para> - - <note> - <para>Because of some unfortunate design limitations with the RCS file - format and CVS's use of vendor branches, minor, trivial and/or - cosmetic changes are <emphasis>strongly discouraged</emphasis> on - files that are still tracking the vendor branch. “Spelling - fixes” are explicitly included here under the - “cosmetic” category and are to be avoided for files with - revision 1.1.x.x. The repository bloat impact from a single character - change can be rather dramatic.</para> - </note> - - <para>The <application>Tcl</application> embedded programming - language will be used as example of how this model works:</para> - - <para><filename>src/contrib/tcl</filename> contains the source as - distributed by the maintainers of this package. Parts that are entirely - not applicable for FreeBSD can be removed. In the case of Tcl, the - <filename>mac</filename>, <filename>win</filename> and - <filename>compat</filename> subdirectories were eliminated before the - import</para> - - <para><filename>src/lib/libtcl</filename> contains only a "bmake style" - <filename>Makefile</filename> that uses the standard - <filename>bsd.lib.mk</filename> makefile rules to produce the library - and install the documentation.</para> - - <para><filename>src/usr.bin/tclsh</filename> contains only a bmake style - <filename>Makefile</filename> which will produce and install the - <command>tclsh</command> program and its associated man-pages using the - standard <filename>bsd.prog.mk</filename> rules.</para> - - <para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of - shell-scripts that can be of help when the tcl software needs updating. - These are not part of the built or installed software.</para> - - <para>The important thing here is that the - <filename>src/contrib/tcl</filename> directory is created according to - the rules: It is supposed to contain the sources as distributed (on a - proper CVS vendor-branch and without RCS keyword expansion) with as few - FreeBSD-specific changes as possible. The 'easy-import' tool on - freefall will assist in doing the import, but if there are any doubts on - how to go about it, it is imperative that you ask first and not blunder - ahead and hope it “works out”. CVS is not forgiving of - import accidents and a fair amount of effort is required to back out - major mistakes.</para> - - <para>Because of the previously mentioned design limitations with CVS's - vendor branches, it is required that “official” patches from - the vendor be applied to the original distributed sources and the result - re-imported onto the vendor branch again. Official patches should never - be patched into the FreeBSD checked out version and "committed", as this - destroys the vendor branch coherency and makes importing future versions - rather difficult as there will be conflicts.</para> - - <para>Since many packages contain files that are meant for compatibility - with other architectures and environments that FreeBSD, it is - permissible to remove parts of the distribution tree that are of no - interest to FreeBSD in order to save space. Files containing copyright - notices and release-note kind of information applicable to the remaining - files shall <emphasis>not</emphasis> be removed.</para> - - <para>If it seems easier, the <command>bmake</command> - <filename>Makefile</filename>s can be produced from the dist tree - automatically by some utility, something which would hopefully make it - even easier to upgrade to a new version. If this is done, be sure to - check in such utilities (as necessary) in the - <filename>src/tools</filename> directory along with the port itself so - that it is available to future maintainers.</para> - - <para>In the <filename>src/contrib/tcl</filename> level directory, a file - called <filename>FREEBSD-upgrade</filename> should be added and it - should states things like:</para> - - <itemizedlist> - <listitem> - <para>Which files have been left out</para> - </listitem> - - <listitem> - <para>Where the original distribution was obtained from and/or the - official master site.</para> - </listitem> - - <listitem> - <para>Where to send patches back to the original authors</para> - </listitem> - - <listitem> - <para>Perhaps an overview of the FreeBSD-specific changes that have - been made.</para> - </listitem> - </itemizedlist> - - <para>However, please do not import <filename>FREEBSD-upgrade</filename> - with the contributed source. Rather you should <command>cvs add - FREEBSD-upgrade ; cvs ci</command> after the initial import. Example - wording from <filename>src/contrib/cpio</filename> is below:</para> - - <programlisting> -This directory contains virgin sources of the original distribution files -on a "vendor" branch. Do not, under any circumstances, attempt to upgrade -the files in this directory via patches and a cvs commit. New versions or -official-patch versions must be imported. Please remember to import with -"-ko" to prevent CVS from corrupting any vendor RCS Ids. - -For the import of GNU cpio 2.4.2, the following files were removed: - - INSTALL cpio.info mkdir.c - Makefile.in cpio.texi mkinstalldirs - -To upgrade to a newer version of cpio, when it is available: - 1. Unpack the new version into an empty directory. - [Do not make ANY changes to the files.] - - 2. Remove the files listed above and any others that don't apply to - FreeBSD. - - 3. Use the command: - cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ - src/contrib/cpio GNU cpio_<version> - - For example, to do the import of version 2.4.2, I typed: - cvs import -ko -m 'Virgin import of GNU v2.4.2' \ - src/contrib/cpio GNU cpio_2_4_2 - - 4. Follow the instructions printed out in step 3 to resolve any - conflicts between local FreeBSD changes and the newer version. - -Do not, under any circumstances, deviate from this procedure. - -To make local changes to cpio, simply patch and commit to the main -branch (aka HEAD). Never make local changes on the GNU branch. - -All local changes should be submitted to "cpio@gnu.ai.mit.edu" for -inclusion in the next vendor release. - -obrien@FreeBSD.org - 30 March 1997</programlisting> - </sect1> - - <sect1 id="policies-encumbered"> - <title>Encumbered files</title> - - <para>It might occasionally be necessary to include an encumbered file in - the FreeBSD source tree. For example, if a device requires a small - piece of binary code to be loaded to it before the device will operate, - and we do not have the source to that code, then the binary file is said - to be encumbered. The following policies apply to including encumbered - files in the FreeBSD source tree.</para> - - <orderedlist> - <listitem> - <para>Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered.</para> - </listitem> - - <listitem> - <para>Any file with a license more restrictive than BSD or GNU is - encumbered.</para> - </listitem> - - <listitem> - <para>A file which contains downloadable binary data for use by the - hardware is not encumbered, unless (1) or (2) apply to it. It must - be stored in an architecture neutral ASCII format (file2c or - uuencoding is recommended).</para> - </listitem> - - <listitem> - <para>Any encumbered file requires specific approval from the <link - linkend="staff-core">Core team</link> before it is added to the - CVS repository.</para> - </listitem> - - <listitem> - <para>Encumbered files go in <filename>src/contrib</filename> or - <filename>src/sys/contrib</filename>.</para> - </listitem> - - <listitem> - <para>The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code.</para> - </listitem> - - <listitem> - <para>Object files are named - <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para> - </listitem> - - <listitem> - <para>Kernel files;</para> - - <orderedlist> - <listitem> - <para>Should always be referenced in - <filename>conf/files.*</filename> (for build simplicity).</para> - </listitem> - - <listitem> - <para>Should always be in <filename>LINT</filename>, but the <link - linkend="staff-core">Core team</link> decides per case if it - should be commented out or not. The <link - linkend="staff-core">Core team</link> can, of course, change - their minds later on.</para> - </listitem> - - <listitem> - <para>The <link linkend="staff-who">Release Engineer</link> - decides whether or not it goes in to the release.</para> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>User-land files;</para> - - <orderedlist> - <listitem> - <para>The <link linkend="staff-core">Core team</link> decides if - the code should be part of <command>make world</command>.</para> - </listitem> - - <listitem> - <para>The <link linkend="staff-who">Release Engineer</link> - decides if it goes in to the release.</para> - </listitem> - </orderedlist> - </listitem> - </orderedlist> - </sect1> - - <sect1 id="policies-shlib"> - <title>Shared Libraries</title> - - <para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien; 9 - December 1996.</emphasis></para> - - <para>If you are adding shared library support to a port or other piece of - software that doesn't have one, the version numbers should follow these - rules. Generally, the resulting numbers will have nothing to do with - the release version of the software.</para> - - <para>The three principles of shared library building are:</para> - - <itemizedlist> - <listitem> - <para>Start from <literal>1.0</literal></para> - </listitem> - - <listitem> - <para>If there is a change that is backwards compatible, bump minor - number</para> - </listitem> - - <listitem> - <para>If there is an incompatible change, bump major number</para> - </listitem> - </itemizedlist> - - <para>For instance, added functions and bugfixes result in the minor - version number being bumped, while deleted functions, changed function - call syntax etc. will force the major version number to change.</para> - - <para>Stick to version numbers of the form major.minor - (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our - dynamic linker does not handle version numbers of the form - <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable> - well. Any version number after the <replaceable>y</replaceable> - (ie. the third digit) is totally ignored when comparing shared lib - version numbers to decide which library to link with. Given two shared - libraries that differ only in the “micro” revision, - <command>ld.so</command> will link with the higher one. Ie: if you link - with <filename>libfoo.so.3.3.3</filename>, the linker only records - <literal>3.3</literal> in the headers, and will link with anything - starting with - <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything >= - 3)</replaceable>.<replaceable>(highest - available)</replaceable>.</para> - - <note> - <para><command>ld.so</command> will always use the highest - “minor” revision. Ie: it will use - <filename>libc.so.2.2</filename> in preference to - <filename>libc.so.2.0</filename>, even if the program was initially - linked with <filename>libc.so.2.0</filename>.</para> - </note> - - <para>For non-port libraries, it is also our policy to change the shared - library version number only once between releases. When you make a - change to a system library that requires the version number to be - bumped, check the <filename>Makefile</filename>'s commit logs. It is the - responsibility of the committer to ensure that the first such change - since the release will result in the shared library version number in - the <filename>Makefile</filename> to be updated, and any subsequent - changes will not.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/ports/chapter.sgml b/en/handbook/ports/chapter.sgml deleted file mode 100644 index b237b41be8..0000000000 --- a/en/handbook/ports/chapter.sgml +++ /dev/null @@ -1,4668 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.43 1999-08-05 20:48:20 nik Exp $ ---> - -<chapter id="ports"> - <title>Installing Applications: The Ports collection</title> - - <para><emphasis>Contributed by &a.jraynard;.</emphasis></para> - - <para>The FreeBSD Ports collection allows you to compile and install a very - wide range of applications with a minimum of effort.</para> - - <para>For all the hype about open standards, getting a program to work on - different versions of Unix in the real world can be a tedious and tricky - business, as anyone who has tried it will know. You may be lucky enough - to find that the program you want will compile cleanly on your system, - install itself in all the right places and run flawlessly “out of - the box”, but this is unfortunately rather rare. With most - programs, you will find yourself doing a fair bit of head-scratching, and - there are quite a few programs that will result in premature greying, or - even chronic alopecia...</para> - - <para>Some software distributions have attacked this problem by providing - configuration scripts. Some of these are very clever, but they have an - unfortunate tendency to triumphantly announce that your system is - something you have never heard of and then ask you lots of questions that - sound like a final exam in system-level Unix programming (<literal>Does - your system's gethitlist function return a const pointer to a fromboz or - a pointer to a const fromboz? Do you have Foonix style unacceptable - exception handling? And if not, why not?</literal>).</para> - - <para>Fortunately, with the Ports collection, all the hard work involved has - already been done, and you can just type <command>make install</command> - and get a working program.</para> - - <sect1> - <title>Why Have a Ports Collection?</title> - - <para>The base FreeBSD system comes with a very wide range of tools and - system utilities, but a lot of popular programs are not in the base - system, for good reasons:-</para> - - <orderedlist> - <listitem> - <para>Programs that some people cannot live without and other people - cannot stand, such as a certain Lisp-based editor.</para> - </listitem> - - <listitem> - <para>Programs which are too specialised to put in the base system - (CAD, databases).</para> - </listitem> - - <listitem> - <para>Programs which fall into the “I must have a look at that - when I get a spare minute” category, rather than - system-critical ones (some languages, perhaps).</para> - </listitem> - - <listitem> - <para>Programs that are far too much fun to be supplied with a serious - operating system like FreeBSD ;-)</para> - </listitem> - - <listitem> - <para>However many programs you put in the base system, people will - always want more, and a line has to be drawn somewhere (otherwise - FreeBSD distributions would become absolutely enormous).</para> - </listitem> - </orderedlist> - - <para>Obviously it would be unreasonable to expect everyone to port their - favourite programs by hand (not to mention a tremendous amount of - duplicated work), so the FreeBSD Project came up with an ingenious way - of using standard tools that would automate the process.</para> - - <para>Incidentally, this is an excellent illustration of how “the - Unix way” works in practice by combining a set of simple but very - flexible tools into something very powerful.</para> - </sect1> - - <sect1> - <title>How Does the Ports Collection Work?</title> - - <para>Programs are typically distributed on the Internet as a <link - linkend="ports-tarball">tarball</link> consisting of a Makefile and - the source code for the program and usually some instructions (which are - unfortunately not always as instructive as they could be), with perhaps - a configuration script.</para> - - <para>The standard scenario is that you FTP down the tarball, extract it - somewhere, glance through the instructions, make any changes that seem - necessary, run the configure script to set things up and use the - standard <command>make</command> program to compile and install the - program from the source.</para> - - <para>FreeBSD ports still use the tarball mechanism, but use a <link - linkend="ports-skeleton">skeleton</link> to hold the - "knowledge" of how to get the program working on FreeBSD, - rather than expecting the user to be able to work it out. They also - supply their own customised <link - linkend="ports-makefile">Makefile</link>, so that almost every port - can be built in the same way.</para> - - <para>If you look at a port skeleton (either on <ulink - URL="file://localhost/usr/ports/devel/ElectricFence">your FreeBSD - system</ulink> or <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports/devel/ElectricFence">the - FTP site</ulink>) and expect to find all sorts of pointy-headed rocket - science lurking there, you may be disappointed by the one or two rather - unexciting-looking files and directories you find there. (We will - discuss in a minute how to go about <link - linkend="ports-getting">Getting a port</link>).</para> - - <para>“How on earth can this do anything?” I hear you cry. - “There is no source code there!”</para> - - <para>Fear not, gentle reader, all will become clear (hopefully). Let us - see what happens if we try and install a port. I have chosen - <application>ElectricFence</application>, a useful tool for developers, - as the skeleton is more straightforward than most.</para> - - <note> - <para>If you are trying this at home, you will need to be root.</para> - </note> - - <screen>&prompt.root; <userinput>cd /usr/ports/devel/ElectricFence</userinput> -&prompt.root; <userinput>make install</userinput> ->> Checksum OK for ElectricFence-2.0.5.tar.gz. -===> Extracting for ElectricFence-2.0.5 -===> Patching for ElectricFence-2.0.5 -===> Applying FreeBSD patches for ElectricFence-2.0.5 -===> Configuring for ElectricFence-2.0.5 -===> Building for ElectricFence-2.0.5 -[lots of compiler output...] -===> Installing for ElectricFence-2.0.5 -===> Warning: your umask is "0002". If this is not desired, set it to - an appropriate value and install this port again by ``make reinstall''. -install -c -o root -g wheel -m 444 /usr/ports/devel/ElectricFence/work/ElectricFence-2.0.5/libefence.a /usr/local/lib -install -c -o root -g wheel -m 444 /usr/ports/devel/ElectricFence/work/ElectricFence-2.0.5/libefence.3 /usr/local/man/man3 -===> Compressing manual pages for ElectricFence-2.0.5 -===> Registering installation for ElectricFence-2.0.5</screen> - - <para>To avoid confusing the issue, I have completely removed the build - output.</para> - - <para>If you tried this yourself, you may well have got something like - this at the start:-</para> - - <screen id="ports-fetch">&prompt.root; <userinput>make install</userinput> ->> ElectricFence-2.0.5.tar.gz doesn't seem to exist on this system. ->> Attempting to fetch from ftp://ftp.doc.ic.ac.uk/Mirrors/sunsite.unc.edu/pub/Linux/devel/lang/c/.</screen> - - <para>The <command>make</command> program has noticed that you did not - have a local copy of the source code and tried to FTP it down so it - could get the job done. I already had the source handy in my example, - so it did not need to fetch it.</para> - - <para>Let's go through this and see what the <command>make</command> - program was doing.</para> - - <procedure> - <step> - <para>Locate the source code <link - linkend="ports-tarball">tarball.</link> If it is not available - locally, try to grab it from an FTP site.</para> - </step> - - <step> - <para>Run a <link linkend="ports-checksum">checksum</link> test on the - tarball to make sure it has not been tampered with, accidentally - truncated, downloaded in ASCII mode, struck by neutrinos while in - transit, etc.</para> - </step> - - <step> - <para>Extract the tarball into a temporary work directory.</para> - </step> - - <step> - <para>Apply any <link linkend="ports-patch">patches</link> needed to - get the source to compile and run under FreeBSD.</para> - </step> - - <step> - <para>Run any configuration script required by the build process and - correctly answer any questions it asks.</para> - </step> - - <step> - <para>(Finally!) Compile the code.</para> - </step> - - <step> - <para>Install the program executable and other supporting files, man - pages, etc. under the <filename>/usr/local</filename> hierarchy - (unless this is an <link linkend="x11">X11</link> program, - then it will be under <filename>/usr/X11R6</filename>), - where they will not get mixed up with system programs. This also - makes sure that all the ports you install will go in the same place, - instead of being flung all over your system.</para> - </step> - - <step> - <para>Register the installation in a database. This means that, if - you do not like the program, you can cleanly <link - linkend="ports-remove">remove</link> all traces of it from your - system.</para> - </step> - </procedure> - - <para>Scroll up to the <command>make</command> output and see if you can - match these steps to it. And if you were not impressed before, you - should be by now!</para> - </sect1> - - <sect1 id="ports-getting"> - <title>Getting a FreeBSD Port</title> - - <para>There are two ways of getting hold of the FreeBSD port for a - program. One requires a <link linkend="ports-cd">FreeBSD CDROM</link>, - the other involves using an <link linkend="ports-inet">Internet - Connection.</link></para> - - <sect2 id="ports-cd"> - <title>Compiling ports from CDROM</title> - - <para>Assuming that your FreeBSD CDROM is in the drive and mounted on - <filename>/cdrom</filename> (and the mount point - <emphasis>must</emphasis> be <filename>/cdrom</filename>), you should - then be able to build ports just as you normally do and the port - collection's built in search path should find the tarballs in - <filename>/cdrom/ports/distfiles/</filename> (if they exist there) - rather than downloading them over the net.</para> - - <para>Another way of doing this, if you want to just use the port - skeletons on the CDROM, is to set these variables in - <filename>/etc/make.conf</filename>:</para> - - <programlisting> -PORTSDIR= /cdrom/ports -DISTDIR= /tmp/distfiles -WRKDIRPREFIX= /tmp</programlisting> - - <para>Substitute <literal>/tmp</literal> for any place you have enough - free space. Then, just <command>cd</command> to the appropriate - subdirectory under <filename>/cdrom/ports</filename> and type - <command>make install</command> as usual. - <makevar>WRKDIRPREFIX</makevar> will cause the port to be build under - <filename>/tmp/cdrom/ports</filename>; for instance, - <filename>games/oneko</filename> will be built under - <filename>/tmp/cdrom/ports/games/oneko</filename>.</para> - - <note> - <para>There are some ports for which we cannot provide the original - source in the CDROM due to licensing limitations. In that case, you - will need to look at the section on <link - linkend="ports-inet">Compiling ports using an Internet - connection.</link></para> - </note> - </sect2> - - <sect2 id="ports-inet"> - <title>Compiling ports from the Internet</title> - - <para>If you do not have a CDROM, or you want to make sure you get the - very latest version of the port you want, you will need to download - the <link linkend="ports-skeleton">skeleton</link> for the port. Now - this might sound like rather a fiddly job full of pitfalls, but it is - actually very easy.</para> - - <para>First, if you are running a release version of FreeBSD, make sure - you get the appropriate “upgrade kit” for your release - from the <ulink url="http://www.FreeBSD.org/ports/">ports web - page</ulink>. These packages include files that have been updated - since the release that you may need to compile new ports.</para> - - <para>The key to the skeletons is that the FreeBSD FTP server can create - on-the-fly <link linkend="ports-tarball">tarballs</link> for you. - Here is how it works, with the gnats program in the databases - directory as an example (the bits in square brackets are comments. Do - not type them in if you are trying this yourself!):-</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>mkdir databases</userinput> -&prompt.root; <userinput>cd databases</userinput> -&prompt.root; <userinput>ftp ftp.FreeBSD.org</userinput> -[log in as `ftp' and give your email address when asked for a -password. Remember to use binary (also known as image) mode!] -<prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/ports/databases</userinput> -<prompt>ftp></prompt> <userinput>get gnats.tar</userinput> -[tars up the gnats skeleton for us] -<prompt>ftp></prompt> <userinput>quit</userinput> -&prompt.root; <userinput>tar xf gnats.tar</userinput> -[extract the gnats skeleton] -&prompt.root; <userinput>cd gnats</userinput> -&prompt.root; <userinput>make install</userinput> -[build and install gnats]</screen> - - <para>What happened here? We connected to the FTP server in the usual - way and went to its <filename>databases</filename> sub-directory. - When we gave it the command <command>get gnats.tar</command>, the FTP - server <link linkend="ports-tarball">tarred</link> up the gnats - directory for us.</para> - - <para>We then extracted the gnats skeleton and went into the gnats - directory to build the port. As we explained <link - linkend="ports-fetch">earlier</link>, the make process noticed we - did not have a copy of the source locally, so it fetched one before - extracting, patching and building it.</para> - - <para>Let us try something more ambitious now. Instead of getting a - single port skeleton, we will get a whole sub-directory, for example all - the database skeletons in the ports collection. It looks almost the - same:-</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>ftp ftp.FreeBSD.org</userinput> -[log in as `ftp' and give your email address when asked for a -password. Remember to use binary (also known as image) mode!] -<prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/ports</userinput> -<prompt>ftp></prompt> <userinput>get databases.tar</userinput> -[tars up the databases directory for us] -<prompt>ftp></prompt> <userinput>quit</userinput> -&prompt.root; <userinput>tar xf databases.tar</userinput> -[extract all the database skeletons] -&prompt.root; <userinput>cd databases</userinput> -&prompt.root; <userinput>make install</userinput> -[build and install all the database ports]</screen> - - <para>With half a dozen straightforward commands, we have now got a set - of database programs on our FreeBSD machine! All we did that was - different from getting a single port skeleton and building it was that - we got a whole directory at once, and compiled everything in it at - once. Pretty impressive, no?</para> - - <para>If you expect to be installing many ports, it is probably worth - downloading all the ports directories.</para> - </sect2> - </sect1> - - <sect1 id="ports-skeleton"> - <title>Skeletons</title> - - <para>A team of compulsive hackers who have forgotten to eat in a frantic - attempt to make a deadline? Something unpleasant lurking in the FreeBSD - attic? No, a skeleton here is a minimal framework that supplies - everything needed to make the ports magic work.</para> - - <sect2 id="ports-makefile"> - <title><filename>Makefile</filename></title> - - <para>The most important component of a skeleton is the Makefile. This - contains various statements that specify how the port should be - compiled and installed. Here is the Makefile for - ElectricFence:-</para> - - <programlisting> -# New ports collection makefile for: Electric Fence -# Version required: 2.0.5 -# Date created: 13 November 1997 -# Whom: jraynard -# -# $Id$ -# - -DISTNAME= ElectricFence-2.0.5 -CATEGORIES= devel -MASTER_SITES= ${MASTER_SITE_SUNSITE} -MASTER_SITE_SUBDIR= devel/lang/c - -MAINTAINER= jraynard@FreeBSD.org - -MAN3= libefence.3 - -do-install: - ${INSTALL_DATA} ${WRKSRC}/libefence.a ${PREFIX}/lib - ${INSTALL_MAN} ${WRKSRC}/libefence.3 ${PREFIX}/man/man3 - -.include <bsd.port.mk></programlisting> - - <para>The lines beginning with a "#" sign are comments for the - benefit of human readers (as in most Unix script files).</para> - - <para><literal>DISTNAME</literal> specifies the name of the <link - linkend="ports-tarball">tarball</link>, but without the - extension.</para> - - <para><literal>CATEGORIES</literal> states what kind of program this is. - In this case, a utility for developers. See the <link - linkend="porting-categories">categories</link> section of this - handbook for a complete list.</para> - - <para><literal>MASTER_SITES</literal> is the URL(s) of the master FTP - site, which is used to retrieve the <link - linkend="ports-tarball">tarball</link> if it is not available on the - local system. This is a site which is regarded as reputable, and is - normally the one from which the program is officially distributed (in - so far as any software is "officially" distributed on the - Internet).</para> - - <para><literal>MAINTAINER</literal> is the email address of the person - who is responsible for updating the skeleton if, for example a new - version of the program comes out.</para> - - <para>Skipping over the next few lines for a minute, the line - <literal>.include <bsd.port.mk></literal> says that the other - statements and commands needed for this port are in a standard file - called <filename>bsd.port.mk</filename>. As these are the same for - all ports, there is no point in duplicating them all over the place, - so they are kept in a single standard file.</para> - - <para>This is probably not the place to go into a detailed examination - of how Makefiles work; suffice it to say that the line starting with - <literal>MAN3</literal> ensures that the ElectricFence man page is - compressed after installation, to help conserve your precious disk - space. The original port did not provide an - <maketarget>install</maketarget> target, so the three lines from - <maketarget>do-install</maketarget> ensure that the files produced by - this port are placed in the correct destination.</para> - </sect2> - - <sect2> - <title>The <filename>files</filename> directory</title> - - <para>The file containing the <link - linkend="ports-checksum">checksum</link> for the port is called - <filename>md5</filename>, after the MD5 algorithm used for ports - checksums. It lives in a directory with the slightly confusing name - of <filename>files</filename>.</para> - - <para>This directory can also contain other miscellaneous files that are - required by the port and do not belong anywhere else.</para> - </sect2> - - <sect2> - <title>The <filename>patches</filename> directory</title> - - <para>This directory contains the <link - linkend="ports-patch">patches</link> needed to make everything work - properly under FreeBSD.</para> - </sect2> - - <sect2> - <title>The <filename>pkg</filename> directory</title> - - <para>This program contains three quite useful files:-</para> - - <itemizedlist> - <listitem> - <para><filename>COMMENT</filename> — a one-line description of - the program.</para> - </listitem> - - <listitem> - <para><filename>DESCR</filename> — a more detailed - description.</para> - </listitem> - - <listitem> - <para><filename>PLIST</filename> — a list of all the files - that will be created when the program is installed.</para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="ports-troubleshooting"> - <title>What to do when a port does not work.</title> - - <para>Oh. You can do one of four (4) things :</para> - - <orderedlist> - <listitem> - <para>Fix it yourself. Technical details on how ports work can be - found in <link linkend="porting">Porting applications.</link></para> - </listitem> - - <listitem> - <para>Gripe. This is done by e-mail <emphasis>only</emphasis>! Send - such e-mail to the maintainer of the port, first. Type - <command>make maintainer</command> or read the - <filename>Makefile</filename> to find the maintainer's email - address. Remember to include the name/version of - the port (copy the <literal>$Id:</literal> line from the - <filename>Makefile</filename>), and the output leading up-to the - error, inclusive. If you do not get a satisfactory response, - you can try filing a bug report with <command>send-pr</command>. - </para> - </listitem> - - <listitem> - <para>Forget it. This is the easiest for most — very few of the - programs in ports can be classified as essential!</para> - </listitem> - - <listitem> - <para>Grab the pre-compiled package from a ftp server. The - “master” package collection is on FreeBSD's FTP server - in the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages - directory</ulink>, though check your local mirror first, please! - These are more likely to work (on the whole) than trying to compile - from source and a lot faster besides! Use the &man.pkg.add.1; - program to install a package file on your - system.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Some Questions and Answers</title> - - <itemizedlist> - <listitem> - <para>Q. I thought this was going to be a discussion about - modems??!</para> - - <para>A. Ah. You must be thinking of the serial ports on the back of - your computer. We are using “port” here to mean the - result of “porting” a program from one version of Unix - to another. (It is an unfortunate bad habit of computer people to - use the same word to refer to several completely different - things).</para> - </listitem> - - <listitem> - <para>Q. I thought you were supposed to use packages to install extra - programs?</para> - - <para>A. Yes, that is usually the quickest and easiest way of doing - it.</para> - </listitem> - - <listitem> - <para>Q. So why bother with ports then?</para> - - <para>A. Several reasons:-</para> - - <orderedlist> - <listitem> - <para>The licensing conditions on some software distributions - require that they be distributed as source code, not - binaries.</para> - </listitem> - - <listitem> - <para>Some people do not trust binary distributions. At least - with source code you can (in theory) read through it and look - for potential problems yourself.</para> - </listitem> - - <listitem> - <para>If you have some local patches, you will need the source to - add them yourself.</para> - </listitem> - - <listitem> - <para>You might have opinions on how a program should be compiled - that differ from the person who did the package — some - people have strong views on what optimisation setting should be - used, whether to build debug versions and then strip them or - not, etc. etc.</para> - </listitem> - - <listitem> - <para>Some people like having code around, so they can read it if - they get bored, hack around with it, borrow from it (licence - terms permitting, of course!) and so on.</para> - </listitem> - - <listitem> - <para>If you ain't got the source, it ain't software! <!-- smiley - -->;-)</para> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para><anchor id="ports-patch"> Q. What is a patch?</para> - - <para>A. A patch is a small (usually) file that specifies how to go - from one version of a file to another. It contains text that says, - in effect, things like “delete line 23”, “add - these two lines after line 468” or “change line 197 to - this”. Also known as a “diff”, since it is - generated by a program of that name.</para> - </listitem> - - <listitem> - <para><anchor id="ports-tarball"> Q. What is all this about - tarballs?</para> - - <para>A. It is a file ending in <filename>.tar</filename> or - <filename>.tar.gz</filename> (with variations like - <filename>.tar.Z</filename>, or even <filename>.tgz</filename> if - you are trying to squeeze the names into a DOS filesystem).</para> - - <para>Basically, it is a directory tree that has been archived into a - single file (<filename>.tar</filename>) and optionally compressed - (<filename>.gz</filename>). This technique was originally used for - <emphasis>T</emphasis>ape <emphasis>AR</emphasis>chives (hence the - name <command>tar</command>), but it is a widely used way of - distributing program source code around the Internet.</para> - - <para>You can see what files are in them, or even extract them - yourself, by using the standard Unix tar program, which comes with - the base FreeBSD system, like this:-</para> - - <screen>&prompt.user; <userinput>tar tvzf foobar.tar.gz</userinput> -&prompt.user; <userinput>tar xzvf foobar.tar.gz</userinput> -&prompt.user; <userinput>tar tvf foobar.tar</userinput> -&prompt.user; <userinput>tar xvf foobar.tar</userinput></screen> - </listitem> - - <listitem> - <para><anchor id="ports-checksum"> Q. And a checksum?</para> - - <para>A. It is a number generated by adding up all the data in the - file you want to check. If any of the characters change, the - checksum will no longer be equal to the total, so a simple - comparison will allow you to spot the difference. (In practice, it - is done in a more complicated way to spot problems like - position-swapping, which will not show up with a simplistic - addition).</para> - </listitem> - - <listitem> - <para>Q. I did what you said for <link linkend="ports-cd">compiling - ports from a CDROM</link> and it worked great until I tried to - install the kermit port:-</para> - - <screen>&prompt.root; <userinput>make install</userinput> ->> cku190.tar.gz doesn't seem to exist on this system. ->> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.</screen> - - <para>Why can it not be found? Have I got a dud CDROM?</para> - - <para>A. The licensing terms for kermit do not allow us to put the - tarball for it on the CDROM, so you will have to fetch it by hand - — sorry! The reason why you got all those error messages was - because you were not connected to the Internet at the time. Once - you have downloaded it from any of the sites above, you can re-start - the process (try and choose the nearest site to you, though, to save - your time and the Internet's bandwidth).</para> - </listitem> - - <listitem> - <para>Q. I did that, but when I tried to put it into - <filename>/usr/ports/distfiles</filename> I got some error about not - having permission.</para> - - <para>A. The ports mechanism looks for the tarball in - <filename>/usr/ports/distfiles</filename>, but you will not be able - to copy anything there because it is sym-linked to the CDROM, which - is read-only. You can tell it to look somewhere else by - doing</para> - - <screen>&prompt.root; <userinput>make DISTDIR=<replaceable>/where/you/put/it</replaceable> install</userinput></screen> - </listitem> - - <listitem> - <para>Q. Does the ports scheme only work if you have everything in - <filename>/usr/ports</filename>? My system administrator says I must - put everything under - <filename>/u/people/guests/wurzburger</filename>, but it does not - seem to work.</para> - - <para>A. You can use the <makevar>PORTSDIR</makevar> and - <makevar>PREFIX</makevar> variables to tell the ports mechanism to - use different directories. For instance,</para> - - <screen>&prompt.root; <userinput>make PORTSDIR=/u/people/guests/wurzburger/ports install</userinput></screen> - - <para>will compile the port in - <filename>/u/people/guests/wurzburger/ports</filename> and install - everything under <filename>/usr/local</filename>.</para> - - <screen>&prompt.root; <userinput>make PREFIX=/u/people/guests/wurzburger/local install</userinput></screen> - - <para>will compile it in <filename>/usr/ports</filename> and install - it in <filename>/u/people/guests/wurzburger/local</filename>.</para> - - <para>And of course</para> - - <screen>&prompt.root; <userinput>make PORTSDIR=.../ports PREFIX=.../local install</userinput></screen> - - <para>will combine the two (it is too long to fit on the page if I - write it in full, but I am sure you get the idea).</para> - - <para>If you do not fancy typing all that in every time you install a - port (and to be honest, who would?), it is a good idea to put these - variables into your environment.</para> - </listitem> - - <listitem> - <para>Q. I do not have a FreeBSD CDROM, but I would like to have all - the tarballs handy on my system so I do not have to wait for a - download every time I install a port. Is there an easy way to get - them all at once?</para> - - <para>A. To get every single tarball for the ports collection, - do</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make fetch</userinput></screen> - - <para>For all the tarballs for a single ports directory, do</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput> -&prompt.root; <userinput>make fetch</userinput></screen> - - <para>and for just one port — well, I think you have guessed - already.</para> - </listitem> - - <listitem> - <para>Q. I know it is probably faster to fetch the tarballs from one - of the FreeBSD mirror sites close by. Is there any way to tell the - port to fetch them from servers other than ones listed in the - MASTER_SITES?</para> - - <para>A. Yes. If you know, for example, <hostid - role="fqdn">ftp.FreeBSD.org</hostid> is much closer than sites - listed in <makevar>MASTER_SITES</makevar>, do as following - example.</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput> -&prompt.root; <userinput>make MASTER_SITE_OVERRIDE=ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen> - </listitem> - - <listitem> - <para>Q. I want to know what files make is going to need before it - tries to pull them down.</para> - - <para>A. <command>make fetch-list</command> will display a list of - the files needed for a port.</para> - </listitem> - - <listitem> - <para>Q. Is there any way to stop the port from compiling? I want to - do some hacking on the source before I install it, but it is a bit - tiresome having to watch it and hit control-C every time.</para> - - <para>A. Doing <command>make extract</command> will stop it after it - has fetched and extracted the source code.</para> - </listitem> - - <listitem> - <para>Q. I am trying to make my own port and I want to be able to - stop it compiling until I have had a chance to see if my patches - worked properly. Is there something like <command>make - extract</command>, but for patches?</para> - - <para>A. Yep, <command>make patch</command> is what you want. You - will probably find the <makevar>PATCH_DEBUG</makevar> option useful - as well. And by the way, thank you for your efforts!</para> - </listitem> - - <listitem> - <para>Q. I have heard that some compiler options can cause bugs. Is - this true? How can I make sure that I compile ports with the right - settings?</para> - - <para>A. Yes, with version 2.6.3 of <command>gcc</command> (the - version shipped with FreeBSD 2.1.0 and 2.1.5), the - <option>-O2</option> option could result in buggy code unless you - used the <option>-fno-strength-reduce</option> option as well. - (Most of the ports do not use <option>-O2</option>). You - <emphasis>should</emphasis> be able to specify the compiler options - used by something like</para> - - - <screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen> - - <para>or by editing <filename>/etc/make.conf</filename>, but - unfortunately not all ports respect this. The surest way is to do - <command>make configure</command>, then go into the source directory - and inspect the Makefiles by hand, but this can get tedious if the - source has lots of sub-directories, each with their own - Makefiles.</para> - </listitem> - - <listitem> - <para>Q. There are so many ports it is hard to find the one I want. - Is there a list anywhere of what ports are available?</para> - - <para>A. Look in the <filename>INDEX</filename> file in - <filename>/usr/ports</filename>. If you would like to search the - ports collection for a keyword, you can do that too. For example, - you can find ports relevant to the LISP programming language - using:</para> - - <screen>&prompt.user; <userinput>cd /usr/ports</userinput> -&prompt.user; <userinput>make search key=lisp</userinput></screen> - </listitem> - - <listitem> - <para>Q. I went to install the <literal>foo</literal> port but the - system suddenly stopped compiling it and starting compiling the - <literal>bar</literal> port. What is going on?</para> - - <para>A. The <literal>foo</literal> port needs something that is - supplied with <literal>bar</literal> — for instance, if - <literal>foo</literal> uses graphics, <literal>bar</literal> might - have a library with useful graphics processing routines. Or - <literal>bar</literal> might be a tool that is needed to compile the - <literal>foo</literal> port.</para> - </listitem> - - <listitem> - <para><anchor id="ports-remove"> Q. I installed the - <literal>grizzle</literal> program from the ports and frankly it is - a complete waste of disk space. I want to delete it but I do not - know where it put all the files. Any clues?</para> - - <para>A. No problem, just do</para> - - <screen>&prompt.root; <userinput>pkg_delete grizzle-6.5</userinput></screen> - - <para>Alternatively, you can do</para> - - <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/grizzle</replaceable></userinput> -&prompt.root; <userinput>make deinstall</userinput></screen> - </listitem> - - <listitem> - <para> - Q. Hang on a minute, you have to know the version number to use - that command. You do not seriously expect me to remember that, do - you??</para> - - <para>A. Not at all, you can find it out by doing</para> - - <screen>&prompt.root; <userinput>pkg_info -a | grep grizzle</userinput> -Information for grizzle-6.5: -grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arcade game.</screen> - </listitem> - - <listitem> - <para>Q. Talking of disk space, the ports directory seems to be - taking up an awful lot of room. Is it safe to go in there and - delete things?</para> - - <para>A. Yes, if you have installed the program and are fairly - certain you will not need the source again, there is no point in - keeping it hanging around. The best way to do this is</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make clean</userinput></screen> - - <para>which will go through all the ports subdirectories and delete - everything except the skeletons for each port.</para> - </listitem> - - <listitem> - <para>Q. I tried that and it still left all those tarballs or - whatever you called them in the <filename>distfiles</filename> - directory. Can I delete those as well?</para> - - <para>A. Yes, if you are sure you have finished with them, those can - go as well.</para> - </listitem> - - <listitem> - <para>Q. I like having lots and lots of programs to play with. Is - there any way of installing all the ports in one go?</para> - - <para>A. Just do</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make install</userinput></screen> - </listitem> - - <listitem> - <para>Q. OK, I tried that, but I thought it would take a very long - time so I went to bed and left it to get on with it. When I looked - at the computer this morning, it had only done three and a half - ports. Did something go wrong?</para> - - <para>A. No, the problem is that some of the ports need to ask you - questions that we cannot answer for you (eg “Do you want to - print on A4 or US letter sized paper?”) and they need to have - someone on hand to answer them.</para> - </listitem> - - <listitem> - <para>Q. I really do not want to spend all day staring at the - monitor. Any better ideas?</para> - - <para>A. OK, do this before you go to bed/work/the local - park:-</para> - - <screen>&prompt.root <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make -DBATCH install</userinput></screen> - - <para>This will install every port that does <emphasis>not</emphasis> - require user input. Then, when you come back, do</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make -DIS_INTERACTIVE install</userinput></screen> - - <para>to finish the job.</para> - </listitem> - - <listitem> - <para>Q. At work, we are using <literal>frobble</literal>, which is - in your ports collection, but we have altered it quite a bit to get - it to do what we need. Is there any way of making our own packages, - so we can distribute it more easily around our sites?</para> - - <para>A. No problem, assuming you know how to make patches for your - changes:-</para> - - <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/frobble</replaceable></userinput> -&prompt.root; <userinput>make extract</userinput> -&prompt.root; <userinput>cd work/frobble-2.8</userinput> -[Apply your patches] -&prompt.root; <userinput>cd ../..</userinput> -&prompt.root; <userinput>make package</userinput></screen> - </listitem> - - <listitem> - <para>Q. This ports stuff is really clever. I am desperate to find - out how you did it. What is the secret?</para> - - <para>A. Nothing secret about it at all, just look at the - <filename>bsd.ports.mk</filename> and - <filename>bsd.ports.subdir.mk</filename> files in your <ulink - URL="file://localhost/usr/ports/Mk/">makefiles - directory.</ulink></para> - - <note> - <para>Readers with an aversion to intricate shell-scripts are - advised not to follow this link...)</para> - </note> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="porting"> - <title>Making a port yourself</title> - - <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami;, &a.obrien;, - and &a.hoek;. 28 August 1996.</emphasis></para> - - <para>So, now you are interested in making your own port or upgrading - an existing one? Great!</para> - - <para>What follows are some guidelines for creating a new port for - FreeBSD. If you want to upgrade an existing port, you should read this - and then read <xref linkend="port-upgrading">.</para> - - <para>When this document is not sufficiently detailed, you should refer to - <filename>/usr/ports/Mk/bsd.port.mk</filename>, which all port Makefiles - include. Even if you do not hack Makefiles daily, it is well - commented, and you will still gain much knowledge from it. - Additionally, you may send specific questions to &a.ports;.</para> - - <note> - <para>Only a fraction of the overridable variables - (<makevar><replaceable>VAR</replaceable></makevar>) are mentioned in - this document. Most (if not all) are documented at the start of - <filename>bsd.port.mk</filename>. This file users a non-standard tab - setting. <application>Emacs</application> and - <application>Vim</application> should recognise the setting on loading - the file. Both <command>vi</command> and <command>ex</command> can be - set to use the correct value by typing <command>:set tabstop=4</command> - once the file has been loaded.</para> - </note> - - <sect2 id="quick-porting"> - <title>Quick Porting</title> - - <para>This section tells you how to do a quick port. In many cases, it - is not enough, but we will see.</para> - - <para>First, get the original tarball and put it into - <makevar>DISTDIR</makevar>, which defaults to - <filename>/usr/ports/distfiles</filename>.</para> - - <note> - <para>The following assumes that the software compiled out-of-the-box, - i.e., there was absolutely no change required for the port to work - on your FreeBSD box. If you needed to change something, you will - have to refer to the next section too.</para> - </note> - - <sect3> - <title>Writing the <filename>Makefile</filename></title> - - <para>The minimal <filename>Makefile</filename> would look something - like this:</para> - - <programlisting> -# New ports collection makefile for: oneko -# Version required: 1.1b -# Date created: 5 December 1994 -# Whom: asami -# -# $Id$ -# - -DISTNAME= oneko-1.1b -CATEGORIES= games -MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - -MAINTAINER= asami@FreeBSD.org - -MAN1= oneko.1 -MANCOMPRESSED= yes -USE_IMAKE= yes - -.include <bsd.port.mk></programlisting> - - <para>See if you can figure it out. Do not worry about the contents - of the <literal>$Id$</literal> line, it will be filled in - automatically by CVS when the port is imported to our main ports - tree. You can find a more detailed example in the <link - linkend="porting-samplem">sample Makefile</link> section.</para> - </sect3> - - <sect3> - <title>Writing the description files</title> - - <para>There are three description files that are required for any - port, whether they actually package or not. They are - <filename>COMMENT</filename>, <filename>DESCR</filename>, and - <filename>PLIST</filename>, and reside in the - <filename>pkg</filename> subdirectory.</para> - - <sect4> - <title><filename>COMMENT</filename></title> - - <para>This is the one-line description of the port. - <emphasis>Please</emphasis> do not include the package name (or - version number of the software) in the comment. The comment - should begin with a capital, and end without a period. Here - is an example:</para> - - <programlisting> -A cat chasing a mouse all over the screen</programlisting> - </sect4> - - <sect4> - <title><filename>DESCR</filename></title> - - <para>This is a longer description of the port. One to a few - paragraphs concisely explaining what the port does is - sufficient.</para> - - <note> - <para>This is <emphasis>not</emphasis> a manual or an in-depth - description on how to use or compile the port! <emphasis>Please - be careful if you are copying from the - <filename>README</filename> or manpage</emphasis>; too often - they are not a concise description of the port or are in an - awkward format (e.g., manpages have justified spacing). If the - ported software has an official WWW homepage, you should list it - here. Prefix <emphasis>one</emphasis> of the websites with - <literal>WWW:</literal> so that automated tools will work - correctly.</para> - </note> - - <para>It is recommended that you sign your name at the end of this - file, as in:</para> - - <programlisting> -This is a port of oneko, in which a cat chases a poor mouse all over -the screen. - : -(etc.) - -WWW: http://www.oneko.org/ - -- Satoshi -asami@cs.berkeley.edu</programlisting> - </sect4> - - <sect4> - <title><filename>PLIST</filename></title> - - <para>This file lists all the files installed by the port. It is - also called the “packing list” because the package is - generated by packing the files listed here. The pathnames are - relative to the installation prefix (usually - <filename>/usr/local</filename> or - <filename>/usr/X11R6</filename>). If you are using the - <makevar>MAN<replaceable>n</replaceable></makevar> variables (as - you should be), do not list any manpages here.</para> - - <para>Here is a small example:</para> - - <programlisting> -bin/oneko -lib/X11/app-defaults/Oneko -lib/X11/oneko/cat1.xpm -lib/X11/oneko/cat2.xpm -lib/X11/oneko/mouse.xpm -@dirrm lib/X11/oneko</programlisting> - - <para>Refer to the &man.pkg.create.1; man page for details on the - packing list.</para> - - <note> - <para>You should list all the files, but not the name directories, - in the list. Also, if the port creates directories for itself - during installation, make sure to add <literal>@dirrm</literal> - lines as necessary to remove them when the port is - deleted.</para> - - <para>It is recommended that you keep all the filenames in this - file sorted alphabetically. It will make verifying the changes - when you upgrade the port much easier.</para> - - <para>Creating a packing list manually can be a very tedious - task. If the port installs a large numbers of files, <link - linkend="porting-autoplist">creating the packing list - automatically</link> might save time.</para> - </note> - </sect4> - </sect3> - - <sect3> - <title>Creating the checksum file</title> - - <para>Just type <command>make makesum</command>. The ports make rules - will automatically generate the file - <filename>files/md5</filename>.</para> - </sect3> - - <sect3 id="porting-testing"> - <title>Testing the port</title> - - <para>You should make sure that the port rules do exactly what you - want it to do, including packaging up the port. These are the - important points you need to verify.</para> - - <itemizedlist> - <listitem> - <para><filename>PLIST</filename> does not contain anything not - installed by your port</para> - </listitem> - - <listitem> - <para><filename>PLIST</filename> contains everything that is - installed by your port</para> - </listitem> - - <listitem> - <para>Your port can be installed multiple times using the - <maketarget>reinstall</maketarget> target</para> - </listitem> - - <listitem> - <para>Your port <link linkend="porting-cleaning">cleans up</link> - after itself upon deinstall</para> - </listitem> - </itemizedlist> - - <procedure> - <title>Recommended test ordering</title> - - <step> - <para><command>make install</command></para> - </step> - - <step> - <para><command>make package</command></para> - </step> - - <step> - <para><command>make deinstall</command></para> - </step> - - <step> - <para><command>pkg_add <replaceable>package-name</replaceable> - </command></para> - </step> - - <step> - <para><command>make deinstall</command></para> - </step> - - <step> - <para><command>make reinstall</command></para> - </step> - - <step> - <para><command>make package</command></para> - </step> - </procedure> - - <para>Make sure that there are not any warnings issued in any of the - <maketarget>package</maketarget> and - <maketarget>deinstall</maketarget> stages, After step 3, check to - see if all the new directories are correctly deleted. Also, try - using the software after step 4, to ensure that is works correctly - when installed from a package.</para> - </sect3> - - <sect3 id="porting-portlint"> - <title>Checking your port with <command>portlint</command></title> - - <para>Please use <command>portlint</command> to see if your port - conforms to our guidelines. The <command>portlint</command> program - is part of the ports collection. In particular, your may want to - check if the <link linkend="porting-samplem">Makefile</link> is in - the right shape and the <link - linkend="porting-pkgname">package</link> is named - appropriately.</para> - </sect3> - - <sect3 id="porting-submitting"> - <title>Submitting the port</title> - - <para>First, make sure you have read the <link - linkend="porting-dads">Do's and Dont's</link> section.</para> - - <para>Now that you are happy with your port, the only thing remaining - is to put it in the main FreeBSD ports tree and make everybody else - happy about it too. We do not need your <filename>work</filename> - directory or the <filename>pkgname.tgz</filename> package, so delete - them now. Next, simply include the output of <command>shar `find - port_dir`</command> in a bug report and send it with the - &man.send-pr.1; program (see <link linkend="contrib-general">Bug - Reports and General Commentary</link> for more information about - &man.send-pr.1;. If the uncompressed port is larger than 20KB, - you should compress it into a tarfile and use &man.uuencode.1; - before including it in the bug report (uuencoded tarfiles are - acceptable even if the bug report is smaller than 20KB but are not - preferred). Be sure to classify the bug report as category - <literal>ports</literal> and class - <literal>change-request</literal>. (Do not mark the report - <literal>confidential</literal>!)</para> - - <para>One more time, <emphasis>do not include the original source - distfile, the <filename>work</filename> directory, or the package - you built with <command>make package</command></emphasis>.</para> - - <note> - <para>In the past, we asked you to upload new port submissions in - our ftp site (<hostid role="fqdn">ftp.FreeBSD.org</hostid>). This - is no longer recommended as read access is turned off on that - <filename>incoming/</filename> directory of that site due to the - large amount of pirated software showing up there.</para> - </note> - - <para>We will look at your port, get back to you if necessary, and put - it in the tree. Your name will also appear in the list of - “Additional FreeBSD contributors” on the FreeBSD - Handbook and other files. Isn't that great?!? <!-- smiley - -->:)</para> - </sect3> - </sect2> - - <sect2> - <title>Slow Porting</title> - - <para>Ok, so it was not that simple, and the port required some - modifications to get it to work. In this section, we will explain, - step by step, how to modify it to get it to work with the ports - paradigm.</para> - - <sect3> - <title>How things work</title> - - <para>First, this is the sequence of events which occurs when the user - first types <command>make</command> in your port's directory, and - you may find that having <filename>bsd.port.mk</filename> in another - window while you read this really helps to understand it.</para> - - <para>But do not worry if you do not really understand what - <filename>bsd.port.mk</filename> is doing, not many people do... - <!-- smiley --><emphasis>:></emphasis></para> - - <procedure> - - <step> - <para>The <maketarget>fetch</maketarget> target is run. The - <maketarget>fetch</maketarget> target is responsible for making - sure that the tarball exists locally in - <makevar>DISTDIR</makevar>. If <maketarget>fetch</maketarget> - cannot find the required files in <makevar>DISTDIR</makevar> it - will look up the URL <makevar>MASTER_SITES</makevar>, which is - set in the Makefile, as well as our main ftp site at <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</ulink>, - where we put sanctioned distfiles as backup. It will then - attempt to fetch the named distribution file with - <makevar>FETCH</makevar>, assuming that the requesting site has - direct access to the Internet. If that succeeds, it will save - the file in <makevar>DISTDIR</makevar> for future use and - proceed.</para> - </step> - - <step> - <para>The <maketarget>extract</maketarget> target is run. It - looks for your port's distribution file (typically a gzip'd - tarball) in <makevar>DISTDIR</makevar> and unpacks it into a - temporary subdirectory specified by <makevar>WRKDIR</makevar> - (defaults to <filename>work</filename>).</para> - </step> - - <step> - <para>The <maketarget>patch</maketarget> target is run. First, - any patches defined in <makevar>PATCHFILES</makevar> are - applied. Second, if any patches are found in - <makevar>PATCHDIR</makevar> (defaults to the - <filename>patches</filename> subdirectory), they are applied at - this time in alphabetical order.</para> - </step> - - <step> - <para>The <maketarget>configure</maketarget> target is run. This - can do any one of many different things.</para> - - <orderedlist> - <listitem> - <para>If it exists, <filename>scripts/configure</filename> is - run.</para> - </listitem> - - <listitem> - <para>If <makevar>HAS_CONFIGURE</makevar> or - <makevar>GNU_CONFIGURE</makevar> is set, - <filename><makevar>WRKSRC</makevar>/configure</filename> is - run.</para> - </listitem> - - <listitem> - <para>If <makevar>USE_IMAKE</makevar> is set, - <makevar>XMKMF</makevar> (default: <command>xmkmf - -a</command>) is run.</para> - </listitem> - </orderedlist> - </step> - - <step> - <para>The <maketarget>build</maketarget> target is run. This is - responsible for descending into the port's private working - directory (<makevar>WRKSRC</makevar>) and building it. If - <makevar>USE_GMAKE</makevar> is set, GNU <command>make</command> - will be used, otherwise the system <command>make</command> will - be used.</para> - </step> - </procedure> - - <para>The above are the default actions. In addition, you can define - targets - <maketarget>pre-<replaceable>something</replaceable></maketarget> or - <maketarget>post-<replaceable>something</replaceable></maketarget>, - or put scripts with those names, in the <filename>scripts</filename> - subdirectory, and they will be run before or after the default - actions are done.</para> - - <para>For example, if you have a <maketarget>post-extract</maketarget> - target defined in your Makefile, and a file - <filename>pre-build</filename> in the <filename>scripts</filename> - subdirectory, the <maketarget>post-extract</maketarget> target will - be called after the regular extraction actions, and the - <filename>pre-build</filename> script will be executed before the - default build rules are done. It is recommended that you use - <filename>Makefile</filename> targets if the actions are simple - enough, because it will be easier for someone to figure out what - kind of non-default action the port requires.</para> - - <para>The default actions are done by the - <filename>bsd.port.mk</filename> targets - <maketarget>do-<replaceable>something</replaceable></maketarget>. - For example, the commands to extract a port are in the target - <maketarget>do-extract</maketarget>. If you are not happy with the - default target, you can fix it by redefining the - <maketarget>do-<replaceable>something</replaceable></maketarget> - target in your <filename>Makefile</filename>.</para> - - <note> - <para>The “main” targets (e.g., - <maketarget>extract</maketarget>, - <maketarget>configure</maketarget>, etc.) do nothing more than - make sure all the stages up to that one are completed and call - the real targets or scripts, and they are not intended to be - changed. If you want to fix the extraction, fix - <maketarget>do-extract</maketarget>, but never ever touch - <maketarget>extract</maketarget>!</para> - </note> - - <para>Now that you understand what goes on when the user types - <command>make</command>, let us go through the recommended steps to - create the perfect port.</para> - </sect3> - - <sect3> - <title>Getting the original sources</title> - - <para>Get the original sources (normally) as a compressed tarball - (<filename><replaceable>foo</replaceable>.tar.gz</filename> or - <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy - it into <makevar>DISTDIR</makevar>. Always use - <emphasis>mainstream</emphasis> sources when and where you - can.</para> - - <para>If you cannot find a ftp/http site that is well-connected to the - net, or can only find sites that have irritatingly non-standard - formats, you might want to put a copy on a reliable ftp or http - server that you control (e.g., your home page). Make sure you set - <makevar>MASTER_SITES</makevar> to reflect your choice.</para> - - <para>If you cannot find somewhere convenient and reliable to put the - distfile (if you are a FreeBSD committer, you can just put it in - your <filename>public_html/</filename> directory on - <hostid>freefall</hostid>), we can “house” it ourselves - by putting it on - <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/LOCAL_PORTS/</filename> - as the last resort. Please refer to this location as - <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to the &a.ports;if - you are not sure what to do.</para> - - <para>If your port's distfile changes all the time for no good reason, - consider putting the distfile in your home page and listing it as - the first <makevar>MASTER_SITES</makevar>. This will prevent users - from getting <errorname>checksum mismatch</errorname> errors, and - also reduce the workload of maintainers of our ftp site. Also, if - there is only one master site for the port, it is recommended that - you house a backup at your site and list it as the second - <makevar>MASTER_SITES</makevar>.</para> - - <para>If your port requires some additional `patches' that are - available on the Internet, fetch them too and put them in - <makevar>DISTDIR</makevar>. Do not worry if they come from a site - other than where you got the main source tarball, we have a way to - handle these situations (see the description of <link - linkend="porting-patchfiles">PATCHFILES</link> below).</para> - </sect3> - - <sect3> - <title>Modifying the port</title> - - <para>Unpack a copy of the tarball in a private directory and make - whatever changes are necessary to get the port to compile properly - under the current version of FreeBSD. Keep <emphasis>careful - track</emphasis> of everything you do, as you will be automating - the process shortly. Everything, including the deletion, addition - or modification of files should be doable using an automated script - or patch file when your port is finished.</para> - - <para>If your port requires significant user interaction/customization - to compile or install, you should take a look at one of Larry Wall's - classic <application>Configure</application> scripts and perhaps do - something similar yourself. The goal of the new ports collection is - to make each port as “plug-and-play” as possible for the - end-user while using a minimum of disk space.</para> - - <note> - <para>Unless explicitly stated, patch files, scripts, and other - files you have created and contributed to the FreeBSD ports - collection are assumed to be covered by the standard BSD copyright - conditions.</para> - </note> - </sect3> - - <sect3> - <title>Patching</title> - - <para>In the preparation of the port, files that have been added or - changed can be picked up with a recursive diff for later feeding to - patch. Each set of patches you wish to apply should be collected - into a file named - <filename>patch-<replaceable>xx</replaceable></filename> where - <replaceable>xx</replaceable> denotes the sequence in which the - patches will be applied — these are done in - <emphasis>alphabetical order</emphasis>, thus <literal>aa</literal> - first, <literal>ab</literal> second and so on. These files should - be stored in <makevar>PATCHDIR</makevar>, from where they will be - automatically applied. All patches should be relative to - <makevar>WRKSRC</makevar> (generally the directory your port's - tarball unpacks itself into, that being where the build is done). - To make fixes and upgrades easier, you should avoid having more than - one patch fix the same file (e.g., <filename>patch-aa</filename> and - <filename>patch-ab</filename> both changing - <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para> - </sect3> - - <sect3> - <title>Configuring</title> - - <para>Include any additional customization commands to your - <filename>configure</filename> script and save it in the - <filename>scripts</filename> subdirectory. As mentioned above, you - can also do this as <filename>Makefile</filename> targets and/or - scripts with the name <filename>pre-configure</filename> or - <filename>post-configure</filename>.</para> - </sect3> - - <sect3> - <title>Handling user input</title> - - <para>If your port requires user input to build, configure or install, - then set <makevar>IS_INTERACTIVE</makevar> in your Makefile. This - will allow “overnight builds” to skip your port if the - user sets the variable <envar>BATCH</envar> in his environment (and - if the user sets the variable <envar>INTERACTIVE</envar>, then - <emphasis>only</emphasis> those ports requiring interaction are - built).</para> - - <para>It is also recommended that if there are reasonable default - answers to the questions, you check the - <makevar>PACKAGE_BUILDING</makevar> variable and turn off the - interactive script when it is set. This will allow us to build the - packages for CD-ROMs and ftp.</para> - </sect3> - </sect2> - - <sect2> - <title>Configuring the Makefile</title> - - <para>Configuring the Makefile is pretty simple, and again we suggest - that you look at existing examples before starting. Also, there is a - <link linkend="porting-samplem">sample Makefile</link> in this - handbook, so take a look and please follow the ordering of variables - and sections in that template to make your port easier for others to - read.</para> - - <para>Now, consider the following problems in sequence as you design - your new Makefile:</para> - - <sect3> - <title>The original source</title> - - <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd - tarball? If so, you can go on to the next step. If not, you should - look at overriding any of the <makevar>EXTRACT_CMD</makevar>, - <makevar>EXTRACT_BEFORE_ARGS</makevar>, - <makevar>EXTRACT_AFTER_ARGS</makevar>, - <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> - variables, depending on how alien a format your port's distribution - file is. (The most common case is - <literal>EXTRACT_SUFX=.tar.Z</literal>, when the tarball is - condensed by regular compress, not gzip.)</para> - - <para>In the worst case, you can simply create your own - <maketarget>do-extract</maketarget> target to override the default, - though this should be rarely, if ever, necessary.</para> - </sect3> - - <sect3> - <title><makevar>DISTNAME</makevar></title> - - <para>You should set <makevar>DISTNAME</makevar> to be the base name - of your port. The default rules expect the distribution file list - (<makevar>DISTFILES</makevar>) to be named - <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> which, if - it is a normal tarball, is going to be something like - <literal>foozolix-1.0.tar.gz</literal> for a setting of - <literal>DISTNAME=foozolix-1.0</literal>.</para> - - <para>The default rules also expect the tarball(s) to extract into a - subdirectory called - <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. - <filename>work/foozolix-1.0/</filename>.</para> - - <para>All this behavior can be overridden, of course; it simply - represents the most common time-saving defaults. For a port - requiring multiple distribution files, simply set - <makevar>DISTFILES</makevar> explicitly. If only a subset of - <makevar>DISTFILES</makevar> are actual extractable archives, then - set them up in <makevar>EXTRACT_ONLY</makevar>, which will override - the <makevar>DISTFILES</makevar> list when it comes to extraction, - and the rest will be just left in <makevar>DISTDIR</makevar> for - later use.</para> - </sect3> - - <sect3> - <title><makevar>PKGNAME</makevar></title> - - <para>If <makevar>DISTNAME</makevar> does not conform to our <link - linkend="porting-pkgname">guidelines for a good package - name</link>, you should set the <makevar>PKGNAME</makevar> - variable to something better. See the abovementioned guidelines for - more details.</para> - </sect3> - - <sect3> - <title><makevar>CATEGORIES</makevar></title> - - <para>When a package is created, it is put under - <filename>/usr/ports/packages/All</filename> and links are made from - one or more subdirectories of - <filename>/usr/ports/packages</filename>. The names of these - subdirectories are specified by the variable - <makevar>CATEGORIES</makevar>. It is intended to make life easier - for the user when he is wading through the pile of packages on the - ftp site or the CD-ROM. Please take a look at the existing <link - linkend="porting-categories">categories</link> and pick the ones - that are suitable for your port.</para> - - <para>This list also determines where in the ports tree the port is - imported. If you put more than one category here, it is assumed - that the port files will be put in the subdirectory with the name in - the first category. See the <link - linkend="porting-categories">categories</link> section for more - discussion about how to pick the right categories.</para> - - <para>If you port truly belongs to something that is different from - all the existing ones, you can even create a new category name. In - that case, please send mail to the &a.ports; to propose a new - category.</para> - - <note> - <para>There is no error checking for category names. <command>make - package</command> will happily create a new directory if you - mistype the category name, so be careful!</para> - </note> - </sect3> - - <sect3> - <title><makevar>MASTER_SITES</makevar></title> - - <para>Record the directory part of the ftp/http-URL pointing at the - original tarball in <makevar>MASTER_SITES</makevar>. Do not forget - the trailing slash (<filename>/</filename>)!</para> - - <para>The <command>make</command> macros will try to use this - specification for grabbing the distribution file with - <makevar>FETCH</makevar> if they cannot find it already on the - system.</para> - - <para>It is recommended that you put multiple sites on this list, - preferably from different continents. This will safeguard against - wide-area network problems, and we are even planning to add support - for automatically determining the closest master site and fetching - from there!</para> - - <para>If the original tarball is part of one of the following popular - archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or Linux Sunsite, you - refer to those sites in an easy compact form using - <makevar>MASTER_SITE_XCONTRIB</makevar>, - <makevar>MASTER_SITE_GNU</makevar>, - <makevar>MASTER_SITE_PERL_CPAN</makevar>, - <makevar>MASTER_SITE_TEX_CTAN</makevar>, and - <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set - <makevar>MASTER_SITE_SUBDIR</makevar> to the path with in the - archive. Here is an example:</para> - - <programlisting> -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications</programlisting> - - <para>The user can also set the <makevar>MASTER_SITE_*</makevar> - variables in <filename>/etc/make.conf</filename> to override our - choices, and use their favorite mirrors of these popular archives - instead.</para> - </sect3> - - <sect3 id="porting-patchfiles"> - <title><makevar>PATCHFILES</makevar></title> - - <para>If your port requires some additional patches that are available - by ftp or http, set <makevar>PATCHFILES</makevar> to the names of - the files and <makevar>PATCH_SITES</makevar> to the URL of the - directory that contains them (the format is the same as - <makevar>MASTER_SITES</makevar>).</para> - - <para>If the patch is not relative to the top of the source tree - (i.e., <makevar>WKRSRC</makevar>) because it contains some extra - pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly. For - instance, if all the pathnames in the patch have an extra - <literal>foozolix-1.0/</literal> in front of the filenames, then set - <literal>PATCH_DIST_STRIP=-p1</literal>.</para> - - <para>Do not worry if the patches are compressed, they will be - decompressed automatically if the filenames end with - <filename>.gz</filename> or <filename>.Z</filename>.</para> - - <para>If the patch is distributed with some other files, such as - documentation, in a gzip'd tarball, you cannot just use - <makevar>PATCHFILES</makevar>. If that is the case, add the name - and the location of the patch tarball to - <makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>. - Then, from the <maketarget>pre-patch</maketarget> target, apply the - patch either by running the patch command from there, or copying the - patch file into the <makevar>PATCHDIR</makevar> directory and - calling it - <filename>patch-<replaceable>xx</replaceable></filename>.</para> - - <note> - <para>Note the tarball will have been extracted alongside the - regular source by then, so there is no need to explicitly extract - it if it is a regular gzip'd or compress'd tarball. If you do the - latter, take extra care not to overwrite something that already - exists in that directory. Also do not forget to add a command to - remove the copied patch in the <maketarget>pre-clean</maketarget> - target.</para> - </note> - </sect3> - - <sect3> - <title><makevar>MAINTAINER</makevar></title> - - <para>Set your mail-address here. Please. <!-- smiley - --><emphasis>:)</emphasis></para> - - <para>For detailed description of the responsibility of maintainers, - refer to <link linkend="policies-maintainer">MAINTAINER on - Makefiles</link> section.</para> - </sect3> - - <sect3> - <title>Dependencies</title> - - <para>Many ports depend on other ports. There are five variables that - you can use to ensure that all the required bits will be on the - user's machine. There are also some pre-supported dependency - variables for common cases, plus a few more to control the behaviour - of dependencies.</para> - - <sect4> - <title><makevar>LIB_DEPENDS</makevar></title> - - <para>This variable specifies the shared libraries this port depends - on. It is a list of - <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples where <replaceable>lib</replaceable> is the name of the - shared library, and <replaceable>dir</replaceable> is the - directory in which to find it in case it is not available, and - <replaceable>target</replaceable> is the target to call in that - directory. For example, <programlisting> LIB_DEPENDS= - jpeg.9:${PORTSDIR}/graphics/jpeg:install</programlisting> - will check for a shared jpeg library with major version 9, and - descend into the <filename>graphics/jpeg</filename> subdirectory - of your ports tree to build and install it if it is not found. - The <replaceable>target</replaceable> part can be omitted if it is - equal to <makevar>DEPENDS_TARGET</makevar> (which defaults to - <literal>install</literal>).</para> - - <note> - <para>The <replaceable>lib</replaceable> part is an argument given - to <command>ldconfig -r | grep -wF</command>. There shall be no - regular expressions in this variable.</para> - </note> - - <para>The dependency is checked twice, once from within the - <maketarget>extract</maketarget> target and then from within the - <maketarget>install</maketarget> target. Also, the name of the - dependency is put in to the package so that - <command>pkg_add</command> will automatically install it if it is - not on the user's system.</para> - </sect4> - - <sect4> - <title><makevar>RUN_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port depends - on during run-time. It is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples where <replaceable>path</replaceable> is the name of the - executable or file, and <replaceable>dir</replaceable> is the - directory in which to find it in case it is not available, and - <replaceable>target</replaceable> is the target to call in that - directory. If <replaceable>path</replaceable> starts with a slash - (<literal>/</literal>), it is treated as a file and its existence - is tested with <command>test -e</command>; otherwise, it is - assumed to be an executable, and <command>which -s</command> is - used to determine if the program exists in the user's search - path.</para> - - <para>For example,</para> - - <programlisting> -RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ - wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting> - - <para>will check if the file or directory - <filename>/usr/local/etc/innd</filename> exists, and build and - install it from the <filename>news/inn</filename> subdirectory of - the ports tree if it is not found. It will also see if an - executable called <command>wish8.0</command> is in your search - path, and descend into the <filename>x11-toolkits/tk80</filename> - subdirectory of your ports tree to build and install it if it is - not found.</para> - - <note> - <para>In this case, <command>innd</command> is actually an - executable; if an executable is in a place that is not expected - to be in a normal user's search path, you should use the full - pathname.</para> - </note> - - <para>The dependency is checked from within the - <maketarget>install</maketarget> target. Also, the name of the - dependency is put in to the package so that - <command>pkg_add</command> will automatically install it if it is - not on the user's system. The <replaceable>target</replaceable> - part can be omitted if it is the same - <makevar>DEPENDS_TARGET</makevar>.</para> - </sect4> - - <sect4> - <title><makevar>BUILD_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port - requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is a - list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples. For example, <programlisting> BUILD_DEPENDS= - unzip:${PORTSDIR}/archivers/unzip</programlisting> will check - for an executable called <command>unzip</command>, and descend - into the <filename>archivers/unzip</filename> subdirectory of your - ports tree to build and install it if it is not found.</para> - - <note> - <para>“build” here means everything from extracting to - compilation. The dependency is checked from within the - <maketarget>extract</maketarget> target. The - <replaceable>target</replaceable> part can be omitted if it is - the same as <makevar>DEPENDS_TARGET</makevar></para> - </note> - </sect4> - - <sect4> - <title><makevar>FETCH_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port - requires to fetch. Like the previous two, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples. For example, <programlisting> FETCH_DEPENDS= - ncftp2:${PORTSDIR}/net/ncftp2</programlisting> will check for an - executable called <command>ncftp2</command>, and descend into the - <filename>net/ncftp2</filename> subdirectory of your ports tree to - build and install it if it is not found.</para> - - <para>The dependency is checked from within the - <maketarget>fetch</maketarget> target. The - <replaceable>target</replaceable> part can be omitted if it is the - same as <makevar>DEPENDS_TARGET</makevar>.</para> - </sect4> - - <sect4> - <title><makevar>DEPENDS</makevar></title> - - <para>If there is a dependency that does not fall into either of the - above four categories, or your port requires to have the source of - the other port extracted in addition to having them installed, - then use this variable. This is a list of - <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>, - as there is nothing to check, unlike the previous four. The - <replaceable>target</replaceable> part can be omitted if it is the - same as <makevar>DEPENDS_TARGET</makevar>.</para> - </sect4> - - <sect4> - <title>Common dependency variables</title> - - <para>Define <literal>USE_XLIB=yes</literal> if your port requires - the X Window System to be installed (it is implied by - <makevar>USE_IMAKE</makevar>). Define - <literal>USE_GMAKE=yes</literal> if your port requires GNU - <command>make</command> instead of BSD <command>make</command>. - Define <literal>USE_AUTOCONF=yes</literal> if your port requires - GNU autoconf to be run. Define <literal>USE_QT=yes</literal> if - your port uses the latest qt toolkit. Use - <literal>USE_PERL5=yes</literal> if your port requires version 5 - of the perl language. (The last is especially important since - some versions of FreeBSD has perl5 as part of the base system - while others do not.)</para> - </sect4> - - <sect4> - <title>Notes on dependencies</title> - - <para>As mentioned above, the default target to call when a - dependency is required is <maketarget>DEPENDS_TARGET</maketarget>. - It defaults to <literal>install</literal>. This is a user - variable; is is never defined in a port's - <filename>Makefile</filename>. If your port needs a special way - to handle a dependency, use the <literal>:target</literal> part of - the <makevar>*_DEPENDS</makevar> variables instead of redefining - <makevar>DEPENDS_TARGET</makevar>.</para> - - <para>When you type <command>make clean</command>, its dependencies - are automatically cleaned too. If you do not wish this to happen, - define the variable <makevar>NOCLEANDEPENDS</makevar> in your - environment.</para> - - <para>To depend on another port unconditionally, it is customary to - use the string <literal>nonexistent</literal> as the first field - of <makevar>BUILD_DEPENDS</makevar> or - <makevar>RUN_DEPENDS</makevar>. Use this only when you need to - the to get to the source of the other port. You can often save - compilation time by specifying the target too. For - instance - - <programlisting> -BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting> - - will always descend to the JPEG port and extract it.</para> - - <para>Do not use <makevar>DEPENDS</makevar> unless there is no other - way the behaviour you want can be accomplished. It will cause the - other port to be always build (and installed, by default), and the - dependency will go into the packages as well. If this is really - what you need, I recommend you write it as - <literal>BUILD_DEPENDS</literal> and - <literal>RUN_DEPENDS</literal> instead—at least the - intention will be clear.</para> - </sect4> - </sect3> - - <sect3> - <title>Building mechanisms</title> - - <para>If your package uses GNU <command>make</command>, set - <literal>USE_GMAKE=yes</literal>. If your package uses - <command>configure</command>, set - <literal>HAS_CONFIGURE=yes</literal>. If your package uses GNU - <command>configure</command>, set - <literal>GNU_CONFIGURE=yes</literal> (this implies - <literal>HAS_CONFIGURE</literal>). If you want to give some extra - arguments to <command>configure</command> (the default argument list - <literal>--prefix=${PREFIX}</literal> for GNU - <command>configure</command> and empty for non-GNU - <command>configure</command>), set those extra arguments in - <makevar>CONFIGURE_ARGS</makevar>. If your package uses GNU - <command>autoconf</command>, set - <literal>USE_AUTOCONF=yes</literal>. This implies - <makevar>GNU_CONFIGURE</makevar>, and will cause - <command>autoconf</command> to be run before - <command>configure</command>.</para> - - <para>If your package is an X application that creates - <filename>Makefile</filename>s from <filename>Imakefile</filename>s - using <command>imake</command>, then set - <literal>USE_IMAKE=yes</literal>. This will cause the configure - stage to automatically do an <command>xmkmf -a</command>. If the - <option>-a</option> flag is a problem for your port, set - <literal>XMKMF=xmkmf</literal>. If the port uses - <command>imake</command> but does not understand the - <maketarget>install.man</maketarget> target, - <literal>NO_INSTALL_MANPAGES=yes</literal> should be set. In - addition, the author of the original port should be shot. <!-- - smiley --><emphasis>:></emphasis></para> - - <para>If your port's source <filename>Makefile</filename> has - something else than <maketarget>all</maketarget> as the main build - target, set <makevar>ALL_TARGET</makevar> accordingly. Same goes - for <maketarget>install</maketarget> and - <makevar>INSTALL_TARGET</makevar>.</para> - </sect3> - </sect2> - - <sect2> - <title>Special considerations</title> - - <para>There are some more things you have to take into account when you - create a port. This section explains the most common of those.</para> - - <sect3 id="porting-ldconfig"> - <title><command>ldconfig</command></title> - - <para>If your port installs a shared library, add a - <maketarget>post-install</maketarget> target to your - <filename>Makefile</filename> that runs <literal>${LDCONFIG} - -m</literal> on the directory where the new library is installed - (usually <filename><makevar>PREFIX</makevar>/lib</filename>) to - register it into the shared library cache.</para> - - <para>Also, add a matching <literal>@exec /sbin/ldconfig -m</literal> - and <literal>@unexec /sbin/ldconfig -R</literal> pair to your - <filename>pkg/PLIST</filename> file so that a user who installed the - package can start using the shared library immediately and - deinstallation will not cause the system to still believe the - library is there. These lines should immediately follow the line - for the shared library itself, as in:</para> - - <programlisting> -lib/libtvl80.so.1 -@exec /sbin/ldconfig -m %D/lib -@unexec /sbin/ldconfig -R</programlisting> - - <para>Never, ever, <emphasis>ever</emphasis> add a line that says - <literal>ldconfig</literal> without any arguments to your - <filename>Makefile</filename> or <filename>pkg/PLIST</filename>. - This will reset the shared library cache to the contents of - <filename>/usr/lib</filename> only, and will royally screw up the - user's machine ("Help, xinit does not run anymore after I install - this port!"). Anybody who does this will be shot and cut in 65,536 - pieces by a rusty knife and have is liver chopped out by a bunch of - crows and will eternally rot to death in the deepest bowels of hell - (not necessarily in that order…)</para> - </sect3> - </sect2> - - <sect2> - <title>ELF support</title> - - <para>Since FreeBSD is moving to ELF shortly after 3.0-RELEASE, we need - to convert many ports that build shared libraries to support ELF. - Complicating this task is that a 3.0 system can run as both ELF and - a.out, and we wish to unofficially support the 2.2 as long as - possible. Below are the guidelines on how to convert a.out only ports - to support both a.out and ELF compilation.</para> - - <para>Some part of this list is only applicable during the conversion, - but will be left here for awhile for reference in case you have come - across some old port you wish to upgrade.</para> - - <sect3> - <title>Moving a.out libraries out of the way</title> - - <para>A.out libraries should be moved out of - <filename>/usr/local/lib</filename> and similar to an - <filename>aout</filename> subdirectory. (If you do not move them out - of the way, ELF ports will happily overwrite a.out libraries.) The - <maketarget>move-aout-libs</maketarget> target in the 3.0-CURRENT - <filename>src/Makefile</filename> (called from - <maketarget>aout-to-elf</maketarget>) will do this for you. It will - only move a.out libs so it is safe to call it on a system with both - ELF and a.out libs in the standard directories.</para> - </sect3> - - <sect3> - <title>Format</title> - - <para>The ports tree will build packages in the format the machine is - in. This means a.out for 2.2 and a.out or ELF for 3.0 depending on - what <command>`objformat`</command> returns. Also, once users move - a.out libraries to a subdirectory, building a.out libraries will be - unsupported. (I.e., it may still work if you know what you are - doing, but you are on your own.)</para> - - <note> - <para>If a port only works for a.out, set - <makevar>BROKEN_ELF</makevar> to a string describing the reason - why. Such ports will be skipped during a build on an ELF - system.</para> - </note> - </sect3> - - <sect3> - <title><makevar>PORTOBJFORMAT</makevar></title> - - <para><filename>bsd.port.mk</filename> will set - <makevar>PORTOBJFORMAT</makevar> to <literal>aout</literal> or - <literal>elf</literal> and export it in the environments - <envar>CONFIGURE_ENV</envar>, <envar>SCRIPTS_ENV</envar> and - <envar>MAKE_ENV</envar>. (It's always going to be - <literal>aout</literal> in 2.2-STABLE). It is also passed to - <maketarget>PLIST_SUB</maketarget> as - <literal>PORTOBJFORMAT=${PORTOBJFORMAT}</literal>. (See comment on - <literal>ldconfig</literal> lines below.)</para> - - <para>The variable is set using this line in - <filename>bsd.port.mk</filename>:</para> - - <programlisting> -PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</programlisting> - - <para>Ports' make processes should use this variable to decide what to - do. However, if the port's <filename>configure</filename> script - already automatically detects an ELF system, it is not necessary to - refer to <makevar>PORTOBJFORMAT</makevar>.</para> - </sect3> - - <sect3> - <title>Building shared libraries</title> - - <para>The following are differences in handling shared libraries for - a.out and ELF.</para> - - <itemizedlist> - <listitem> - <para>Shared library versions</para> - - <para>An ELF shared library should be called - <filename>libfoo.so.<replaceable>M</replaceable></filename> - where <replaceable>M</replaceable> is the single version number, - and an a.out library should be called - <filename>libfoo.so.<replaceable>M</replaceable>.<replaceable>N</replaceable></filename> - where <replaceable>M</replaceable> is the major version and - <replaceable>N</replaceable> is the the minor version number. - Do not mix those; <emphasis>never</emphasis> install an ELF - shared library called - <filename>libfoo.so.<replaceable>N</replaceable>.<replaceable>M</replaceable></filename> - or an a.out shared library (or symlink) called - <filename>libfoo.so.<replaceable>N</replaceable></filename>.</para> - </listitem> - - <listitem> - <para>Linker command lines</para> - - <para>Assuming <command>cc -shared</command> is used rather than - <command>ld</command> directly, the only difference is that you - need to add - <option>-Wl,-<replaceable>soname,libfoo.so.M</replaceable></option> - on the command line for ELF.</para> - </listitem> - </itemizedlist> - - <para>You need to install a symlink from - <filename>libfoo.so</filename> to - <filename>libfoo.so.<replaceable>N</replaceable></filename> to make - ELF linkers happy. Since it should be listed in - <filename>PLIST</filename> too, and it won't hurt in the a.out case - (some ports even require the link for dynamic loading), you should - just make this link regardless of the setting of - <makevar>PORTOBJFORMAT</makevar>.</para> - </sect3> - - <sect3> - <title><makevar>LIB_DEPENDS</makevar></title> - - <para>All port Makefiles are edited to remove minor numbers from - <makevar>LIB_DEPENDS</makevar>, and also to have the regexp support - removed. (E.g., <literal>foo\\.1\\.\\(33|40\\)</literal> becomes - <literal>foo.2</literal>.) They will be matched using <command>grep - -wF</command>.</para> - </sect3> - - <sect3> - <title><filename>PLIST</filename></title> - - <para><filename>PLIST</filename> should contain the short (ELF) shlib - names if the a.out minor number is zero, and the long (a.out) names - otherwise. <filename>bsd.port.mk</filename> will automatically add - <literal>.0</literal> to the end of short shlib lines if - <makevar>PORTOBJFORMAT</makevar> equals <literal>aout</literal>, and - will delete the minor number from long shlib names if - <makevar>PORTOBJFORMAT</makevar> equals - <literal>elf</literal>.</para> - - <para>In cases where you really need to install shlibs with two - versions on an ELF system or those with one version on an a.out - system (for instance, ports that install compatibility libraries for - other operating systems), define the variable - <makevar>NO_FILTER_SHLIBS</makevar>. This will turn off the editing - of <filename>PLIST</filename> mentioned in the previous - paragraph.</para> - </sect3> - - <sect3> - <title><literal>ldconfig</literal></title> - - <para>The <literal>ldconfig</literal> line in Makefiles should - read:</para> - - <programlisting> -${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting> - - <para>In <filename>PLIST</filename> it should read;</para> - - <programlisting> -@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ... -@unexec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -R</programlisting> - - <para>This is to ensure that the correct <command>ldconfig</command> - will be called depending on the format of the package, not the - default format of the system.</para> - </sect3> - </sect2> - - <sect2 id="porting-masterdir"> - <title><makevar>MASTERDIR</makevar></title> - - <para>If your port needs to build slightly different versions of - packages by having a variable (for instance, resolution, or paper - size) take different values, create one subdirectory per package to - make it easier for users to see what to do, but try to share as many - files as possible between ports. Typically you only need a very short - <filename>Makefile</filename> in all but one of the directories if you - use variables cleverly. In the sole <filename>Makefiles</filename>, - you can use <makevar>MASTERDIR</makevar> to specify the directory - where the rest of the files are. Also, use a variable as part of - <link linkend="porting-pkgname"><makevar>PKGNAME</makevar></link> so - the packages will have different names.</para> - - <para>This will be best demonstrated by an example. This is part of - <filename>japanese/xdvi300/Makefile</filename>;</para> - - <programlisting> -PKGNAME= ja-xdvi${RESOLUTION}-17 - : -# default -RESOLUTION?= 300 -.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ - ${RESOLUTION} != 300 && ${RESOLUTION} != 400 - @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" - @${ECHO} "Possible values are: 118, 240, 300 (default) and 400." - @${FALSE} -.endif</programlisting> - - <para><filename>japanese/xdvi300</filename> also has all the regular - patches, package files, etc. If you type <command>make</command> - there, it will take the default value for the resolution (300) and - build the port normally.</para> - - <para>As for other resolutions, this is the <emphasis>entire</emphasis> - <filename>xdvi118/Makefile</filename>;</para> - - <programlisting> -RESOLUTION= 118 -MASTERDIR= ${.CURDIR}/../xdvi300 - -.include ${MASTERDIR}/Makefile</programlisting> - - <para>(<filename>xdvi240/Makefile</filename> and - <filename>xdvi400/Makefile</filename> are similar). The - <makevar>MASTERDIR</makevar> definition tells - <filename>bsd.port.mk</filename> that the regular set of - subdirectories like <makevar>PATCHDIR</makevar> and - <makevar>PKGDIR</makevar> are to be found under - <filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal> - line will override the <literal>RESOLUTION=300</literal> line in - <filename>xdvi300/Makefile</filename> and the port will be built with - resolution set to 118.</para> - </sect2> - - <sect2> - <title>Shared library versions</title> - - <para>First, please read our <link linkend="policies-shlib">policy on - shared library versioning</link> to understand what to do with - shared library versions in general. Do not blindly assume software - authors know what they are doing; many of them do not. It is very - important that these details are carefully considered, as we have - quite a unique situation where we are trying to have dozens of - potentially incompatible software pairs co-exist. Careless port - imports have caused great trouble regarding shared libraries in the - past (ever wondered why the port <filename>jpeg-6b</filename> has a - shared library version of 9.0?). If in doubt, send a message to the - &a.ports;. Most of the time, your job ends by determining the right - shared library version and making appropriate patches to implement - it.</para> - - <para>However, if there is a port which is a different version of the - same software already in the tree, the situation is much more complex. - In short, the FreeBSD implementation does not allow the user to - specify to the linker which version of shared library to link against - (the linker will always pick the highest numbered version). This - means, if there is a <filename>libfoo.so.3.2</filename> and - <filename>libfoo.so.4.0</filename> in the system, there is no way to - tell the linker to link a particular application to - <filename>libfoo.so.3.2</filename>. It is essentially completely - overshadowed in terms of compilation-time linkage. In this case, the - only solution is to rename the <emphasis>base</emphasis> part of the - shared library. For instance, change - <filename>libfoo.so.4.0</filename> to - <filename>libfoo4.so.1.0</filename> so both version 3.2 and 4.0 can be - linked from other ports.</para> - </sect2> - - <sect2 id="porting-manpages"> - <title>Manpages</title> - - <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically add - any manpages to <filename>pkg/PLIST</filename> (this means you must - <emphasis>not</emphasis> list manpages in the - <filename>PLIST</filename>—see <link - linkend="porting-plist">generating PLIST</link> for more). It also - makes the install stage automatically compress or uncompress manpages - depending on the setting of <makevar>NOMANCOMPRESS</makevar> in - <filename>/etc/make.conf</filename>.</para> - - <para>If your port tries to install multiple names for manpages using - symlinks or hardlinks, you must use the <makevar>MLINKS</makevar> - variable to identify these. The link installed by your port will - be destroyed and recreated by <filename>bsd.port.mk</filename> - to make sure it points to the correct file. Any manpages - listed in MLINKS must not be listed in the - <filename>PLIST</filename>.</para> - - <para>To specify whether the manpages are compressed upon installation, - use the <makevar>MANCOMPRESSED</makevar> variable. This variable can - take three values, <literal>yes</literal>, <literal>no</literal> and - <literal>maybe</literal>. <literal>yes</literal> means manpages are - already installed compressed, <literal>no</literal> means they are - not, and <literal>maybe</literal> means the software already respects - the value of <makevar>NOMANCOMPRESS</makevar> so - <filename>bsd.port.mk</filename> does not have to do anything - special.</para> - - <para><makevar>MANCOMPRESSED</makevar> is automatically set to - <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and - <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to - <literal>no</literal> otherwise. You do not have to explicitly define - it unless the default is not suitable for your port.</para> - - <para>If your port anchors its man tree somewhere other than - <makevar>PREFIX</makevar>, you can use the - <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in - certain sections go in a non-standard place, such as some Perl modules - ports, you can set individual man paths using - <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where - <replaceable>sect</replaceable> is one of <literal>1-9</literal>, - <literal>L</literal> or <literal>N</literal>).</para> - - <para>If your manpages go to language-specific subdirectories, set the - name of the languages to <makevar>MANLANG</makevar>. The value of - this variable defaults to <literal>""</literal> (i.e., English - only).</para> - - <para>Here is an example that puts it all together.</para> - - <programlisting> -MAN1= foo.1 -MAN3= bar.3 -MAN4= baz.4 -MLINKS= foo.1 alt-name.8 -MANLANG= "" ja -MAN3PREFIX= ${PREFIX}/share/foobar -MANCOMPRESSED= yes</programlisting> - - <para>This states that six files are installed by this port;</para> - - <programlisting> -${PREFIX}/man/man1/foo.1.gz -${PREFIX}/man/ja/man1/foo.1.gz -${PREFIX}/share/foobar/man/man3/bar.3.gz -${PREFIX}/share/foobar/man/ja/man3/bar.3.gz -${PREFIX}/man/man4/baz.4.gz -${PREFIX}/man/ja/man4/baz.4.gz</programlisting> - - <para>Additionally <filename>${PREFIX}/man/man8/alt-name.8.gz</filename> - may or may-not be installed by your port. Regardless, a - symlink will be made to join the foo(1) manpage and - alt-name(8) manpage.</para> - - </sect2> - - <sect2 id="porting-motif"> - <title>Ports that require Motif</title> - - <para>There are many programs that require a Motif library (available - from several commercial vendors, while there is a free clone reported - to be able to run many applications in - <filename>x11-toolkits/lesstif</filename>) to compile. Since it is a - popular toolkit and their licenses usually permit redistribution of - statically linked binaries, we have made special provisions for - handling ports that require Motif in a way that we can easily compile - binaries linked either dynamically (for people who are compiling from - the port) or statically (for people who distribute packages).</para> - - <sect3> - <title><makevar>REQUIRES_MOTIF</makevar></title> - - <para>If your port requires Motif, define this variable in the - Makefile. This will prevent people who do not own a copy of Motif - from even attempting to build it.</para> - </sect3> - - <sect3> - <title><makevar>MOTIFLIB</makevar></title> - - <para>This variable will be set by <filename>bsd.port.mk</filename> to - be the appropriate reference to the Motif library. Please patch the - source to use this wherever the Motif library is referenced in the - <filename>Makefile</filename> or - <filename>Imakefile</filename>.</para> - - <para>There are two common cases:</para> - - <itemizedlist> - <listitem> - <para>If the port refers to the Motif library as - <literal>-lXm</literal> in its <filename>Makefile</filename> or - <filename>Imakefile</filename>, simply substitute - <literal>${MOTIFLIB}</literal> for it.</para> - </listitem> - - <listitem> - <para>If the port uses <literal>XmClientLibs</literal> in its - <filename>Imakefile</filename>, change it to - <literal>${MOTIFLIB} ${XTOOLLIB} - ${XLIB}</literal>.</para> - </listitem> - </itemizedlist> - - <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to - <literal>-L/usr/X11R6/lib -lXm</literal> or - <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need to - add <literal>-L</literal> or <literal>-l</literal> in front.</para> - </sect3> - </sect2> - - <sect2> - <title>X11 fonts</title> - - <para>If your port installs fonts for the X Window system, put them in - <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>. - This directory is new to XFree86 release 3.3.3. If it does not exist, - please create it, and print out a message urging the user to update - their XFree86 to 3.3.3 or newer, or at least add this directory to the - font path in <filename>/etc/XF86Config</filename>.</para> - </sect2> - - <sect2> - <title>Info files</title> - - <para>The new version of texinfo (included in 2.2.2-RELEASE and onwards) - contains a utility called <command>install-info</command> to add and - delete entries to the <filename>dir</filename> file. If your port - installs any info documents, please follow this instructions so your - port/package will correctly update the user's - <filename><makevar>PREFIX</makevar>/info/dir</filename> file. (Sorry - for the length of this section, but is it imperative to weave all the - info files together. If done correctly, it will produce a - <emphasis>beautiful</emphasis> listing, so please bear with me!</para> - - <para>First, this is what you (as a porter) need to know</para> - - <screen>&prompt.user; <userinput>install-info --help</userinput> -install-info [OPTION]... [INFO-FILE [DIR-FILE]] - Install INFO-FILE in the Info directory file DIR-FILE. - -Options: ---delete Delete existing entries in INFO-FILE; - don't insert any new entries. - : ---entry=TEXT Insert TEXT as an Info directory entry. - : ---section=SEC Put this file's entries in section SEC of the directory. :</screen> - - <note> - <para>This program will not actually <emphasis>install</emphasis> info - files; it merely inserts or deletes entries in the - <filename>dir</filename> file.</para> - </note> - - <para>Here's a seven-step procedure to convert ports to use - <command>install-info</command>. I will use - <filename>editors/emacs</filename> as an example.</para> - - <procedure> - <step> - <para>Look at the texinfo sources and make a patch to insert - <literal>@dircategory</literal> and <literal>@direntry</literal> - statements to files that do not have them. This is part of my - patch:</para> - - <programlisting> ---- ./man/vip.texi.org Fri Jun 16 15:31:11 1995 -+++ ./man/vip.texi Tue May 20 01:28:33 1997 -@@ -2,6 +2,10 @@ - - @setfilename ../info/vip - @settitle VIP -+@dircategory The Emacs editor and associated tools -+@direntry -+* VIP: (vip). A VI-emulation for Emacs. -+@end direntry - - @iftex - @finalout - :</programlisting> - - <para>The format should be self-explanatory. Many authors leave a - <filename>dir</filename> file in the source tree that contains all - the entries you need, so look around before you try to write your - own. Also, make sure you look into related ports and make the - section names and entry indentations consistent (we recommend that - all entry text start at the 4th tab stop).</para> - - <note> - <para>Note that you can put only one info entry per file because - of a bug in <command>install-info --delete</command> that - deletes only the first entry if you specify multiple entries in - the <email>@direntry</email> section.</para> - </note> - - <para>You can give the <literal>dir</literal> entries to - <command>install-info</command> as arguments - (<option>--section</option> and <option>--entry</option>) instead - of patching the texinfo sources. I do not think this is a good - idea for ports because you need to duplicate the same information - in <emphasis>three</emphasis> places - (<filename>Makefile</filename> and - <literal>@exec</literal>/<literal>@unexec</literal> of - <filename>PLIST</filename>; see below). However, if you have a - Japanese (or other multibyte encoding) info files, you will have - to use the extra arguments to <command>install-info</command> - because <command>makeinfo</command> cannot handle those texinfo - sources. (See <filename>Makefile</filename> and - <filename>PLIST</filename> of <filename>japanese/skk</filename> - for examples on how to do this).</para> - </step> - - <step> - <para>Go back to the port directory and do a <command>make clean; - make</command> and verify that the info files are regenerated - from the texinfo sources. Since the texinfo sources are newer than - the info files, they should be rebuilt when you type - <command>make</command>; but many <filename>Makefile</filename>s - do not include correct dependencies for info files. In - <command>emacs</command>' case, I had to patch the main - <filename>Makefile.in</filename> so it will descend into the - <filename>man</filename> subdirectory to rebuild the info - pages.</para> - - <programlisting> ---- ./Makefile.in.org Mon Aug 19 21:12:19 1996 -+++ ./Makefile.in Tue Apr 15 00:15:28 1997 -@@ -184,7 +184,7 @@ - # Subdirectories to make recursively. `lisp' is not included - # because the compiled lisp files are part of the distribution - # and you cannot remake them without installing Emacs first. --SUBDIR = lib-src src -+SUBDIR = lib-src src man - - # The makefiles of the directories in $SUBDIR. - SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile ---- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996 -+++ ./man/Makefile.in Tue Apr 15 00:29:52 1997 -@@ -66,6 +66,7 @@ - ${srcdir}/gnu1.texi \ - ${srcdir}/glossary.texi - -+all: info - info: $(INFO_TARGETS) - - dvi: $(DVI_TARGETS)</programlisting> - - <para>The second hunk was necessary because the default target in - the <filename>man</filename> subdir is called - <maketarget>info</maketarget>, while the main - <filename>Makefile</filename> wants to call - <maketarget>all</maketarget>. I also deleted the installation of - the <filename>info</filename> info file because we already have - one with the same name in <filename>/usr/share/info</filename> - (that patch is not shown here).</para> - </step> - - <step> - <para>If there is a place in the <filename>Makefile</filename> that - is installing the <filename>dir</filename> file, delete it. Your - port may not be doing it. Also, remove any commands that are - otherwise mucking around with the <filename>dir</filename> - file.</para> - - <programlisting> ---- ./Makefile.in.org Mon Aug 19 21:12:19 1996 -+++ ./Makefile.in Mon Apr 14 23:38:07 1997 -@@ -368,14 +368,8 @@ - if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \ - then \ - (cd ${infodir}; \ -- if [ -f dir ]; then \ -- if [ ! -f dir.old ]; then mv -f dir dir.old; \ -- else mv -f dir dir.bak; fi; \ -- fi; \ - cd ${srcdir}/info ; \ -- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \ -- (cd $${thisdir}; chmod a+r ${infodir}/dir); \ - for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \ - (cd $${thisdir}; \ - ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ - chmod a+r ${infodir}/$$f); \</programlisting> - </step> - - <step> - <para>(This step is only necessary if you are modifying an existing - port.) Take a look at <filename>pkg/PLIST</filename> and delete - anything that is trying to patch up <filename>info/dir</filename>. - They may be in <filename>pkg/INSTALL</filename> or some other - file, so search extensively.</para> - - <programlisting> -Index: pkg/PLIST -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v -retrieving revision 1.15 -diff -u -r1.15 PLIST ---- PLIST 1997/03/04 08:04:00 1.15 -+++ PLIST 1997/04/15 06:32:12 -@@ -15,9 +15,6 @@ - man/man1/emacs.1.gz - man/man1/etags.1.gz - man/man1/ctags.1.gz --@unexec cp %D/info/dir %D/info/dir.bak --info/dir --@unexec cp %D/info/dir.bak %D/info/dir - info/cl - info/cl-1 - info/cl-2</programlisting> - </step> - - <step> - <para>Add a <maketarget>post-install</maketarget> target to the - <filename>Makefile</filename> to create a <filename>dir</filename> - file if it is not there. Also, call - <maketarget>install-info</maketarget> with the installed info - files.</para> - - <programlisting> -Index: Makefile -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/Makefile,v -retrieving revision 1.26 -diff -u -r1.26 Makefile ---- Makefile 1996/11/19 13:14:40 1.26 -+++ Makefile 1997/05/20 10:25:09 1.28 -@@ -20,5 +20,11 @@ - post-install: - .for file in emacs-19.34 emacsclient etags ctags b2m - strip ${PREFIX}/bin/${file} - .endfor -+ if [ ! -f ${PREFIX}/info/dir ]; then \ -+ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \ -+ fi -+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode -+ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir -+.endfor - - .include <bsd.port.mk></programlisting> - - <para>Do not use anything other than - <filename>/usr/share/info/dir</filename> and the above command to - create a new info file. In fact, I would add the first three lines - of the above patch to <filename>bsd.port.mk</filename> if you (the - porter) would not have to do it in <filename>PLIST</filename> by - yourself anyway.</para> - </step> - - <step> - <para>Edit <filename>PLIST</filename> and add equivalent - <literal>@exec</literal> statements and also - <literal>@unexec</literal> for <command>pkg_delete</command>. You - do not need to delete <filename>info/dir</filename> with - <literal>@unexec</literal>.</para> - - <programlisting> -Index: pkg/PLIST -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v -retrieving revision 1.15 -diff -u -r1.15 PLIST ---- PLIST 1997/03/04 08:04:00 1.15 -+++ PLIST 1997/05/20 10:25:12 1.17 -@@ -16,7 +14,15 @@ - man/man1/etags.1.gz - man/man1/ctags.1.gz -+@unexec install-info --delete %D/info/emacs %D/info/dir - : -+@unexec install-info --delete %D/info/ccmode %D/info/dir - info/cl - info/cl-1 -@@ -87,6 +94,18 @@ - info/viper-3 - info/viper-4 -+@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir -+@exec install-info %D/info/emacs %D/info/dir - : -+@exec install-info %D/info/ccmode %D/info/dir - libexec/emacs/19.34/i386--freebsd/cvtmail - libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting> - - <note> - <para>The <literal>@unexec install-info --delete</literal> - commands have to be listed before the info files themselves so - they can read the files. Also, the <literal>@exec - install-info</literal> commands have to be after the info - files and the <literal>@exec</literal> command that creates the - the <filename>dir</filename> file.</para> - </note> - </step> - - <step> - <para><link linkend="porting-testing">Test</link> and admire your - work. <!-- smiley --><emphasis>:)</emphasis>. Check the - <filename>dir</filename> file before and after each step.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>The <filename>pkg/</filename> subdirectory</title> - - <para>There are some tricks we have not mentioned yet about the - <filename>pkg/</filename> subdirectory that come in handy - sometimes.</para> - - <sect3 id="porting-message"> - <title><filename>MESSAGE</filename></title> - - <para>If you need to display a message to the installer, you may place - the message in <filename>pkg/MESSAGE</filename>. This capability is - often useful to display additional installation steps to be taken - after a <command>pkg_add</command> or to display licensing - information.</para> - - <note> - <para>The <filename>pkg/MESSAGE</filename> file does not need to be - added to <filename>pkg/PLIST</filename>. Also, it will not get - automatically printed if the user is using the port, not the - package, so you should probably display it from the - <maketarget>post-install</maketarget> target yourself.</para> - </note> - </sect3> - - <sect3> - <title><filename>INSTALL</filename></title> - - <para>If your port needs to execute commands when the binary package - is installed with <command>pkg_add</command> you can do this via the - <filename>pkg/INSTALL</filename> script. This script will - automatically be added to the package, and will be run twice by - <command>pkg_add</command>. The first time will as <literal>INSTALL - ${PKGNAME} PRE-INSTALL</literal> and the second time as - <literal>INSTALL ${PKGNAME} POST-INSTALL</literal>. - <literal>$2</literal> can be tested to determine which mode - the script is being run in. The <envar>PKG_PREFIX</envar> - environmental variable will be set to the package installation - directory. See &man.pkg.add.1; for - additional information.</para> - - <note> - <para>This script is not run automatically if you install the port - with <command>make install</command>. If you are depending on it - being run, you will have to explicitly call it from your port's - <filename>Makefile</filename>.</para> - </note> - </sect3> - - <sect3> - <title><filename>REQ</filename></title> - - <para>If your port needs to determine if it should install or not, you - can create a <filename>pkg/REQ</filename> “requirements” - script. It will be invoked automatically at - installation/deinstallation time to determine whether or not - installation/deinstallation should proceed.</para> - </sect3> - - <sect3 id="porting-plist"> - <title>Changing <filename>PLIST</filename> based on make - variables</title> - - <para>Some ports, particularly the p5- ports, need to change their - <filename>PLIST</filename> depending on what options they are - configured with (or version of perl, in the case of p5- ports). To - make this easy, any instances in the <filename>PLIST</filename> of - <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and - <literal>%%PERL_VERSION%%</literal> will be substituted for - appropriately. The value of <literal>%%OSREL%%</literal> is the - numeric revision of the operating system (e.g., - <literal>2.2.7</literal>). <literal>%%PERL_VERSION%%</literal> is - the full version number of perl (e.g., <literal>5.00502</literal>) - and <literal>%%PERL_VER%%</literal> is the perl version number minus - the patchlevel (e.g., <literal>5.005</literal>).</para> - - <para>If you need to make other substitutions, you can set the - <makevar>PLIST_SUB</makevar> variable with a list of - <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> - pairs and instances of - <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be - substituted with <replaceable>VALUE</replaceable> in the - <filename>PLIST</filename>.</para> - - <para>For instance, if you have a port that installs many files in a - version-specific subdirectory, you can put something like - - <programlisting> -OCTAVE_VERSION= 2.0.13 -PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting> - - in the <filename>Makefile</filename> and use - <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows up - in <filename>PLIST</filename>. That way, when you upgrade the port, - you will not have to change dozens (or in some cases, hundreds) of - lines in the <filename>PLIST</filename>.</para> - - <para>This substitution (as well as addition of any <link - linkend="porting-manpages">man pages</link>) will be done between - the <maketarget>do-install</maketarget> and - <maketarget>post-install</maketarget> targets, by reading from - <makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar> - (default: - <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). So if - your port builds <makevar>PLIST</makevar> on the fly, do so in or - before <maketarget>do-install</maketarget>. Also, if your port - needs to edit the resulting file, do so in - <maketarget>post-install</maketarget> to a file named - <makevar>TMPPLIST</makevar>.</para> - </sect3> - - <sect3> - <title id="porting-pkgsubdir">Changing the names of files in the - <filename>pkg</filename> subdirectory</title> - - <para>All the filenames in the <filename>pkg</filename> subdirectory - are defined using variables so you can change them in your - <filename>Makefile</filename> if need be. This is especially useful - when you are sharing the same <filename>pkg</filename> subdirectory - among several ports or have to write to one of the above files (see - <link linkend="porting-wrkdir">writing to places other than - <makevar>WRKDIR</makevar></link> for why it is a bad idea to write - directly in to the <filename>pkg</filename> subdirectory.</para> - - <para>Here is a list of variable names and their default - values.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - <entry>Default value</entry> - </row> - </thead> - - <tbody> - <row> - <entry><makevar>COMMENT</makevar></entry> - <entry><literal>${PKGDIR}/DESCR</literal></entry> - </row> - - <row> - <entry><makevar>DESCR</makevar></entry> - <entry><literal>${PKGDIR}/DESCR</literal></entry> - </row> - - <row> - <entry><makevar>PLIST</makevar></entry> - <entry><literal>${PKGDIR}/PLIST</literal></entry> - </row> - - <row> - <entry><makevar>PKGINSTALL</makevar></entry> - <entry><literal>${PKGDIR}/PKGINSTALL</literal></entry> - </row> - - <row> - <entry><makevar>PKGDEINSTALL</makevar></entry> - <entry><literal>${PKGDIR}/PKGDEINSTALL</literal></entry> - </row> - - <row> - <entry><makevar>PKGREQ</makevar></entry> - <entry><literal>${PKGDIR}/REQ</literal></entry> - </row> - - <row> - <entry><makevar>PKGMESSAGE</makevar></entry> - <entry><literal>${PKGDIR}/MESSAGE</literal></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Please change these variables rather than overriding - <makevar>PKG_ARGS</makevar>. If you change - <makevar>PKG_ARGS</makevar>, those files will not correctly be - installed in <filename>/var/db/pkg</filename> upon install from a - port.</para> - </sect3> - </sect2> - - <sect2> - <title>Licensing Problems</title> - - <para>Some software packages have restrictive licenses or can be in - violation to the law (PKP's patent on public key crypto, ITAR (export - of crypto software) to name just two of them). What we can do with - them varies a lot, depending on the exact wordings of the respective - licenses.</para> - - <note> - <para>It is your responsibility as a porter to read the licensing - terms of the software and make sure that the FreeBSD project will - not be held accountable of violating them by redistributing the - source or compiled binaries either via ftp or CD-ROM. If in doubt, - please contact the &a.ports;.</para> - </note> - - <para>There are two variables you can set in the Makefile to handle the - situations that arise frequently:</para> - - <orderedlist> - <listitem> - <para>If the port has a “do not sell for profit” type of - license, set the variable <makevar>NO_CDROM</makevar> to a string - describing the reason why. We will make sure such ports will not go - into the CD-ROM come release time. The distfile and package will - still be available via ftp.</para> - </listitem> - - <listitem> - <para>If the resulting package needs to be built uniquely for each - site, or the resulting binary package cannot be distributed due to - licensing; set the variable <makevar>NO_PACKAGE</makevar> to a - string describing the reason why. We will make sure such packages - will not go on the ftp site, nor into the CD-ROM come release time. - The distfile will still be included on both however.</para> - </listitem> - - <listitem> - <para>If the port has legal restrictions on who can use it (e.g., - crypto stuff) or has a “no commercial use” license, - set the variable <makevar>RESTRICTED</makevar> to be the string - describing the reason why. For such ports, the distfiles/packages - will not be available even from our ftp sites.</para> - </listitem> - </orderedlist> - - <note> - <para>The GNU General Public License (GPL), both version 1 and 2, - should not be a problem for ports.</para> - </note> - - <note> - <para>If you are a committer, make sure you update the - <filename>ports/LEGAL</filename> file too.</para> - </note> - </sect2> - - <sect2 id="port-upgrading"> - <title>Upgrading</title> - - <para>When you notice that a port is out of date compared to the latest - version from the original authors, first make sure you have the latest - port. You can find them in the - <filename>ports/ports-current</filename> directory of the ftp mirror - sites. You may also use CVSup to keep your whole ports collection - up-to-date, as described in <xref linkend="cvsup-config">.</para> - - <para>The next step is to send a mail to the maintainer, if one is - listed in the port's <filename>Makefile</filename>. That person may - already be working on an upgrade, or have a reason to not upgrade the - port right now (because of, for example, stability problems of the new - version).</para> - - <para>If the maintainer asks you to do the upgrade or there is not any - such person to begin with, please make the upgrade and send the - recursive diff (either unified or context diff is fine, but port - committers appear to prefer unified diff more) of the new and old - ports directories to us (e.g., if your modified port directory is - called <filename>superedit</filename> and the original as in our tree - is <filename>superedit.bak</filename>, then send us the result of - <command>diff -ruN superedit.bak superedit</command>). Please examine - the output to make sure all the changes make sense. The best way to - send us the diff is by including it to &man.send-pr.1; (category - <literal>ports</literal>). Please mention any added or deleted files - in the message, as they have to be explicitly specified to CVS when - doing a commit. If the diff is more than about 20KB, please compress - and uuencode it; otherwise, just include it in as is in the PR.</para> - - <note> - <para>Once again, please use &man.diff.1; and not &man.shar.1; to send - updates to existing ports!</para> - </note> - </sect2> - - <sect2> - <title><anchor id="porting-dads">Do's and Dont's</title> - - <para>Here is a list of common do's and dont's that you encounter during - the porting process.You should check your own port against this list, - but you can also check ports in the PR database that others have - submitted. Submit any comments on ports you check as described in - <link linkend="contrib-general">Bug Reports and General - Commentary</link>. Checking ports in the PR database will both make - it faster for us to commit them, and prove that you know what you are - doing.</para> - - <sect3> - <title>Strip Binaries</title> - - <para>Do strip binaries. If the original source already strips the - binaries, fine; otherwise you should add a - <literal>post-install</literal> rule to to it yourself. Here is an - example;</para> - - <programlisting> -post-install: - strip ${PREFIX}/bin/xdl</programlisting> - - <para>Use the &man.file.1; command on the installed executable to - check whether the binary is stripped or not. If it does not say - <literal>not stripped</literal>, it is stripped.</para> - </sect3> - - <sect3> - <title>INSTALL_* macros</title> - - <para>Do use the macros provided in <filename>bsd.port.mk</filename> - to ensure correct modes and ownership of files in your own - <maketarget>*-install</maketarget> targets. They are:</para> - - <itemizedlist> - <listitem> - <para><makevar>INSTALL_PROGRAM</makevar> is a command to install - binary executables.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_SCRIPT</makevar> is a command to install - executable scripts.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_DATA</makevar> is a command to install - sharable data.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_MAN</makevar> is a command to install - manpages and other documentation (it does not compress - anything).</para> - </listitem> - </itemizedlist> - - <para>These are basically the <command>install</command> command with - all the appropriate flags. See below for an example on how to use - them.</para> - </sect3> - - <sect3 id="porting-wrkdir"> - <title><makevar>WRKDIR</makevar></title> - - <para>Do not write anything to files outside - <makevar>WRKDIR</makevar>. <makevar>WRKDIR</makevar> is the only - place that is guaranteed to be writable during the port build (see - <link linkend="ports-cd">compiling ports from CDROM</link> for an - example of building ports from a read-only tree). If you need to - modify some file in <makevar>PKGDIR</makevar>, do so by <link - linkend="porting-pkgsubdir">redefining a variable</link>, not by - writing over it.</para> - </sect3> - - <sect3 id="porting-wrkdirprefix"> - <title><makevar>WRKDIRPREFIX</makevar></title> - - <para>Make sure your port honors <makevar>WRKDIRPREFIX</makevar>. - Most ports do not have to worry about this. In particular, if you - are referring to a <makevar>WRKDIR</makevar> of another port, note - that the correct location is - <filename><makevar>WRKDIRPREFIX</makevar><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> not <filename><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> or <filename><makevar>.CURDIR</makevar>/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> or some such.</para> - - <para>Also, if you are defining <makevar>WRKDIR</makevar> yourself, - make sure you prepend - <literal>${WKRDIRPREFIX}${.CURDIR}</literal> in the - front.</para> - </sect3> - - <sect3 id="porting-versions"> - <title>Differentiating operating systems and OS versions</title> - - <para>You may come across code that needs modifications or conditional - compilation based upon what version of UNIX it is running under. If - you need to make such changes to the code for conditional - compilation, make sure you make the changes as general as possible - so that we can back-port code to FreeBSD 1.x systems and cross-port - to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD, - NetBSD, and OpenBSD.</para> - - <para>The preferred way to tell 4.3BSD/Reno (1990) and newer versions - of the BSD code apart is by using the <literal>BSD</literal> macro - defined in <filename><sys/param.h></filename>. Hopefully that - file is already included; if not, add the code:</para> - - <programlisting> -#if (defined(__unix__) || defined(unix)) && !defined(USG) -#include <sys/param.h> -#endif</programlisting> - - <para>to the proper place in the <filename>.c</filename> file. We - believe that every system that defines these two symbols has - <filename>sys/param.h</filename>. If you find a system that - does not, we would like to know. Please send mail to the - &a.ports;.</para> - - <para>Another way is to use the GNU Autoconf style of doing - this:</para> - - <programlisting> -#ifdef HAVE_SYS_PARAM_H -#include <sys/param.h> -#endif</programlisting> - - <para>Do not forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to the - <makevar>CFLAGS</makevar> in the <filename>Makefile</filename> for - this method.</para> - - <para>Once you have <filename>sys/param.h</filename> included, you may - use:</para> - - <programlisting> -#if (defined(BSD) && (BSD >= 199103))</programlisting> - - <para>to detect if the code is being compiled on a 4.3 Net2 code base - or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 - 1.1 and below).</para> - - <para>Use:</para> - - <programlisting> -#if (defined(BSD) && (BSD >= 199306))</programlisting> - - <para>to detect if the code is being compiled on a 4.4 code base or - newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or - above).</para> - - <para>The value of the <literal>BSD</literal> macro is - <literal>199506</literal> for the 4.4BSD-Lite2 code base. This is - stated for informational purposes only. It should not be used to - distinguish between versions of FreeBSD based only on 4.4-Lite vs. - versions that have merged in changes from 4.4-Lite2. The - <literal>__FreeBSD__</literal> macro should be used instead.</para> - - <para>Use sparingly:</para> - - <itemizedlist> - <listitem> - <para><literal>__FreeBSD__</literal> is defined in all versions of - FreeBSD. Use it if the change you are making - <emphasis>only</emphasis> affects FreeBSD. Porting gotchas like - the use of <literal>sys_errlist[]</literal> vs - <function>strerror()</function> are Berkeleyisms, not FreeBSD - changes.</para> - </listitem> - - <listitem> - <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is defined to - be <literal>2</literal>. In earlier versions, it is - <literal>1</literal>. Later versions will bump it to match - their major version number.</para> - </listitem> - - <listitem> - <para>If you need to tell the difference between a FreeBSD 1.x - system and a FreeBSD 2.x or 3.x system, usually the right answer - is to use the <literal>BSD</literal> macros described above. If - there actually is a FreeBSD specific change (such as special - shared library options when using <command>ld</command>) then it - is OK to use <literal>__FreeBSD__</literal> and <literal>#if - __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x and later - system. If you need more granularity in detecting FreeBSD - systems since 2.0-RELEASE you can use the following:</para> - - <programlisting> -#if __FreeBSD__ >= 2 -#include <osreldate.h> -# if __FreeBSD_version >= 199504 - /* 2.0.5+ release specific code here */ -# endif -#endif</programlisting> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Release</entry> - <entry><literal>__FreeBSD_version</literal></entry> - </row> - </thead> - - <tbody> - <row> - <entry>2.0-RELEASE</entry> - <entry>119411</entry> - </row> - - <row> - <entry>2.1-CURRENTs</entry> - <entry>199501, 199503</entry> - </row> - - <row> - <entry>2.0.5-RELEASE</entry> - <entry>199504</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1</entry> - <entry>199508</entry> - </row> - - <row> - <entry>2.1.0-RELEASE</entry> - <entry>199511</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1.5</entry> - <entry>199512</entry> - </row> - - <row> - <entry>2.1.5-RELEASE</entry> - <entry>199607</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1.6</entry> - <entry>199608</entry> - </row> - - <row> - <entry>2.1.6-RELEASE</entry> - <entry>199612</entry> - </row> - - <row> - <entry>2.1.7-RELEASE</entry> - <entry>199612</entry> - </row> - - <row> - <entry>2.2-RELEASE</entry> - <entry>220000</entry> - </row> - - <row> - <entry>2.2.1-RELEASE</entry> - <entry>220000 (no change)</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.1-RELEASE</entry> - <entry>220000 (no change)</entry> - </row> - - <row> - <entry>2.2-STABLE after texinfo-3.9</entry> - <entry>221001</entry> - </row> - - <row> - <entry>2.2-STABLE after top</entry> - <entry>221002</entry> - </row> - - <row> - <entry>2.2.2-RELEASE</entry> - <entry>222000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.2-RELEASE</entry> - <entry>222001</entry> - </row> - - <row> - <entry>2.2.5-RELEASE</entry> - <entry>225000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.5-RELEASE</entry> - <entry>225001</entry> - </row> - - <row> - <entry>2.2-STABLE after ldconfig -R merge</entry> - <entry>225002</entry> - </row> - - <row> - <entry>2.2.6-RELEASE</entry> - <entry>226000</entry> - </row> - - <row> - <entry>2.2.7-RELEASE</entry> - <entry>227000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.7-RELEASE</entry> - <entry>227001</entry> - </row> - - <row> - <entry>2.2-STABLE after semctl(2) change</entry> - <entry>227002</entry> - </row> - - <row> - <entry>2.2.8-RELEASE</entry> - <entry>228000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.8-RELEASE</entry> - <entry>228001</entry> - </row> - - <row> - <entry>3.0-CURRENT before mount(2) change</entry> - <entry>300000</entry> - </row> - - <row> - <entry>3.0-CURRENT after mount(2) change</entry> - <entry>300001</entry> - </row> - - <row> - <entry>3.0-CURRENT after semctl(2) change</entry> - <entry>300002</entry> - </row> - - <row> - <entry>3.0-CURRENT after ioctl arg changes</entry> - <entry>300003</entry> - </row> - - <row> - <entry>3.0-CURRENT after ELF conversion</entry> - <entry>300004</entry> - </row> - - <row> - <entry>3.0-RELEASE</entry> - <entry>300005</entry> - </row> - - <row> - <entry>3.0-CURRENT after 3.0-RELEASE</entry> - <entry>300006</entry> - </row> - - <row> - <entry>3.0-STABLE after 3/4 branch</entry> - <entry>300007</entry> - </row> - - <row> - <entry>3.1-RELEASE</entry> - <entry>310000</entry> - </row> - - <row> - <entry>3.1-STABLE after 3.1-RELEASE</entry> - <entry>310001</entry> - </row> - - <row> - <entry>3.1-STABLE after C++ constructor/destructor order - change</entry> - <entry>310002</entry> - </row> - - <row> - <entry>3.2-STABLE</entry> - <entry>320001</entry> - </row> - - <row> - <entry>4.0-CURRENT after 3/4 branch</entry> - <entry>400000</entry> - </row> - - <row> - <entry>4.0-CURRENT after change in dynamic linker - handling</entry> - <entry>400001</entry> - </row> - - <row> - <entry>4.0-CURRENT after C++ constructor/destructor - order change</entry> - <entry>400002</entry> - </row> - - <row> - <entry>4.0-CURRENT after functioning dladdr(3)</entry> - <entry>400003</entry> - </row> - - <row> - <entry>4.0-CURRENT after newbus</entry> - <entry>400004</entry> - </row> - - <row> - <entry>4.0-CURRENT after suser(9) API change</entry> - <entry>400005</entry> - </row> - - <row> - <entry>4.0-CURRENT after cdevsw registration change</entry> - <entry>400006</entry> - </row> - - <row> - <entry>4.0-CURRENT after the addition of so_cred for - socket level credentials</entry> - <entry>400007</entry> - </row> - - <row> - <entry>4.0-CURRENT after the addition of a poll syscall - wrapper to libc_r</entry> - <entry>400008</entry> - </row> - - <row> - <entry>4.0-CURRENT after the change of the kernel's - <literal>dev_t</literal> type to <literal>struct - spacinfo</literal> pointer</entry> - <entry>400009</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </listitem> - </itemizedlist> - - <note> - <para>Note that 2.2-STABLE sometimes identifies itself as - “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern - used to be year followed by the month, but we decided to change it - to a more straightforward major/minor system starting from 2.2. - This is because the parallel development on several branches made - it infeasible to classify the releases simply by their real - release dates. If you are making a port now, you do not have to - worry about old -CURRENTs; they are listed here just for your - reference.</para> - </note> - - <para>In the hundreds of ports that have been done, there have only - been one or two cases where <literal>__FreeBSD__</literal> should - have been used. Just because an earlier port screwed up and used it - in the wrong place does not mean you should do so too.</para> - </sect3> - - <sect3> - <title>Writing something after - <filename>bsd.port.mk</filename></title> - - <para>Do not write anything after the <literal>.include - <bsd.port.mk></literal> line. it usually can be avoided by - including <filename>bsd.port.pre.mk</filename> somewhere in the - middle of your <filename>Makefile</filename> and - <filename>bsd.port.post.mk</filename> at the end.</para> - - <note> - <para>You need to include either the - <filename>pre.mk</filename>/<filename>post.mk</filename> pair or - <filename>bsd.port.mk</filename> only; do not mix these two.</para> - </note> - - <para><filename>bsd.port.pre.mk</filename> only defines a few - variables, which can be used in tests in the - <filename>Makefile</filename>, <filename>bsd.port.post.mk</filename> - defines the rest.</para> - - <para>Here are some important variables defined in - <filename>bsd.port.pre.mk</filename> (this is not the complete list, - please read <filename>bsd.port.mk</filename> for the complete - list).</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><makevar>ARCH</makevar></entry> - <entry>The architecture as returned by <command>uname - -m</command> (e.g., <literal>i386</literal>)</entry> - </row> - - <row> - <entry><makevar>OPSYS</makevar></entry> - <entry>The operating system type, as returned by - <command>uname -s</command> (e.g., - <literal>FreeBSD</literal>)</entry> - </row> - - <row> - <entry><makevar>OSREL</makevar></entry> - <entry>The release version of the operating system (e.g., - <literal>2.1.5</literal> or - <literal>2.2.7</literal>)</entry> - </row> - - <row> - <entry><makevar>OSVERSION</makevar></entry> - <entry>The numeric version of the operating system, same as - <link - linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry> - </row> - - <row> - <entry><makevar>PORTOBJFORMAT</makevar></entry> - <entry>The object format of the system - (<literal>aout</literal> or <literal>elf</literal></entry> - </row> - - <row> - <entry><makevar>LOCALBASE</makevar></entry> - <entry>The base of the “local” tree (e.g., - <literal>/usr/local/</literal>)</entry> - </row> - - <row> - <entry><makevar>X11BASE</makevar></entry> - <entry>The base of the “X11” tree (e.g., - <literal>/usr/X11R6</literal>)</entry> - </row> - - <row> - <entry><makevar>PREFIX</makevar></entry> - <entry>Where the port installs itself (see <link - linkend="porting-prefix">more on - <makevar>PREFIX</makevar></link>).</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>If you have to define the variables - <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>, or - <makevar>MASTERDIR</makevar>, do so before including - <filename>bsd.port.pre.mk</filename>.</para> - </note> - - <para>Here are some examples of things you can write after - <filename>bsd.port.pre.mk</filename>;</para> - - <programlisting> -# no need to compile lang/perl5 if perl5 is already in system -.if ${OSVERSION} > 300003 -BROKEN= perl is in system -.endif - -# only one shlib version number for ELF -.if ${PORTOBJFORMAT} == "elf" -TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR} -.else -TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR} -.endif - -# software already makes link for ELF, but not for a.out -post-install: -.if ${PORTOBJFORMAT} == "aout" - ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so -.endif</programlisting> - </sect3> - - <sect3> - <title>Install additional documentation</title> - - <para>If your software has some documentation other than the standard - man and info pages that you think is useful for the user, install it - under <filename><makevar>PREFIX</makevar>/share/doc</filename>. - This can be done, like the previous item, in the - <maketarget>post-install</maketarget> target.</para> - - <para>Create a new directory for your port. The directory name should - reflect what the port is. This usually means - <makevar>PKGNAME</makevar> minus the version part. However, if you - think the user might want different versions of the port to be - installed at the same time, you can use the whole - <makevar>PKGNAME</makevar>.</para> - - <para>Make the installation dependent to the variable - <makevar>NOPORTDOCS</makevar> so that users can disable it in - <filename>/etc/make.conf</filename>, like this:</para> - - <programlisting> -post-install: -.if !defined(NOPORTDOCS) - ${MKDIR}${PREFIX}/share/doc/xv - ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv -.endif</programlisting> - - <para>Do not forget to add them to <filename>pkg/PLIST</filename> too! - (Do not worry about <makevar>NOPORTDOCS</makevar> here; there is - currently no way for the packages to read variables from - <filename>/etc/make.conf</filename>.)</para> - - <para>Also you can use the <filename>pkg/MESSAGE</filename> file to - display messages upon installation. See the <link - linkend="porting-message">using - <filename>pkg/MESSAGE</filename></link> section for - details.</para> - - <note> - <para><filename>MESSAGE</filename> does not need to be added to - <filename>pkg/PLIST</filename>).</para> - </note> - </sect3> - - <sect3> - <title><makevar>DIST_SUBDIR</makevar></title> - - <para>Do not let your port clutter - <filename>/usr/ports/distfiles</filename>. If your port requires a - lot of files to be fetched, or contains a file that has a name that - might conflict with other ports (e.g., - <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> - to the name of the port (<makevar>PKGNAME</makevar> without the - version part should work fine). This will change - <makevar>DISTDIR</makevar> from the default - <filename>/usr/ports/distfiles</filename> to - <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>, - and in effect puts everything that is required for your port into - that subdirectory.</para> - - <para>It will also look at the subdirectory with the same name on the - backup master site at <filename>ftp.FreeBSD.org</filename>. - (Setting <makevar>DISTDIR</makevar> explicitly in your - <makevar>Makefile</makevar> will not accomplish this, so please use - <makevar>DIST_SUBDIR</makevar>.)</para> - - <note> - <para>This does not affect the <makevar>MASTER_SITES</makevar> you - define in your Makefile.</para> - </note> - </sect3> - - <sect3> - <title>Package information</title> - - <para>Do include package information, i.e. - <filename>COMMENT</filename>, <filename>DESCR</filename>, and - <filename>PLIST</filename>, in <filename>pkg</filename>.</para> - - <note> - <para>Note that these files are not used only for packaging anymore, - and are <emphasis>mandatory</emphasis> now, even if - <makevar>NO_PACKAGE</makevar> is set.</para> - </note> - </sect3> - - <sect3> - <title>RCS strings</title> - - <para>Do not put RCS strings in patches. CVS will mangle them when we - put the files into the ports tree, and when we check them out again, - they will come out different and the patch will fail. RCS strings - are surrounded by dollar (<literal>$</literal>) signs, and - typically start with <literal>$Id</literal> or - <literal>$RCS</literal>.</para> - </sect3> - - <sect3> - <title>Recursive diff</title> - - <para>Using the recurse (<option>-r</option>) option to - <command>diff</command> to generate patches is fine, but please take - a look at the resulting patches to make sure you do not have any - unnecessary junk in there. In particular, diffs between two backup - files, <filename>Makefiles</filename> when the port uses - <command>Imake</command> or GNU <command>configure</command>, etc., - are unnecessary and should be deleted. If you had to edit - <filename>configure.in</filename> and run - <command>autoconf</command> to regenerate - <command>configure</command>, do not take the diffs of - <command>configure</command> (it often grows to a few thousand - lines!); define <literal>USE_AUTOCONF=yes</literal> and take the - diffs of <filename>configure.in</filename>.</para> - - <para>Also, if you had to delete a file, then you can do it in the - <maketarget>post-extract</maketarget> target rather than as part of - the patch. Once you are happy with the resulting diff, please split - it up into one source file per patch file.</para> - </sect3> - - <sect3 id="porting-prefix"> - <title><makevar>PREFIX</makevar></title> - - <para>Do try to make your port install relative to - <makevar>PREFIX</makevar>. (The value of this variable will be set - to <makevar>LOCALBASE</makevar> (default - <filename>/usr/local</filename>), unless - <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is - set, in which case it will be <makevar>X11BASE</makevar> (default - <filename>/usr/X11R6</filename>).)</para> - - <para>Not hard-coding <filename>/usr/local</filename> or - <filename>/usr/X11R6</filename> anywhere in the source will make the - port much more flexible and able to cater to the needs of other - sites. For X ports that use <command>imake</command>, this is - automatic; otherwise, this can often be done by simply replacing the - occurrences of <filename>/usr/local</filename> (or - <filename>/usr/X11R6</filename> for X ports that do not use imake) - in the various scripts/Makefiles in the port to read - <makevar>PREFIX</makevar>, as this variable is automatically passed - down to every stage of the build and install processes.</para> - - <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port - truly require it (i.e., it links against X libs or it needs to - reference files in <makevar>X11BASE</makevar>).</para> - - <para>The variable <makevar>PREFIX</makevar> can be reassigned in your - <filename>Makefile</filename> or in the user's environment. - However, it is strongly discouraged for individual ports to set this - variable explicitly in the <filename>Makefiles</filename>.</para> - - <para>Also, refer to programs/files from other ports with the - variables mentioned above, not explicit pathnames. For instance, if - your port requires a macro <literal>PAGER</literal> to be the full - pathname of <command>less</command>, use the compiler flag: - - <programlisting> --DPAGER=\"${PREFIX}/bin/less\"</programlisting> - - or - - <programlisting> --DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> - - if this is an X port, instead of - <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will - have a better chance of working if the system administrator has - moved the whole `/usr/local' tree somewhere else.</para> - </sect3> - - <sect3> - <title>Subdirectories</title> - - <para>Try to let the port put things in the right subdirectories of - <makevar>PREFIX</makevar>. Some ports lump everything and put it in - the subdirectory with the port's name, which is incorrect. Also, - many ports put everything except binaries, header files and manual - pages in the a subdirectory of <filename>lib</filename>, which does - not bode well with the BSD paradigm. Many of the files should be - moved to one of the following: <filename>etc</filename> - (setup/configuration files), <filename>libexec</filename> - (executables started internally), <filename>sbin</filename> - (executables for superusers/managers), <filename>info</filename> - (documentation for info browser) or <filename>share</filename> - (architecture independent files). See man &man.hier.7; for details, - the rules governing - <filename>/usr</filename> pretty much apply to - <filename>/usr/local</filename> too. The exception are ports - dealing with USENET “news”. They may use - <filename><makevar>PREFIX</makevar>/news</filename> as a destination - for their files.</para> - </sect3> - - <sect3 id="porting-cleaning"> - <title>Cleaning up empty directories</title> - - <para>Do make your ports clean up after themselves when they are - deinstalled. This is usually accomplished by adding - <literal>@dirrm</literal> lines for all directories that are - specifically created by the port. You need to delete subdirectories - before you can delete parent directories.</para> - - <programlisting> - : -lib/X11/oneko/pixmaps/cat.xpm -lib/X11/oneko/sounds/cat.au - : -@dirrm lib/X11/oneko/pixmaps -@dirrm lib/X11/oneko/sounds -@dirrm lib/X11/oneko</programlisting> - - <para>However, sometimes <literal>@dirrm</literal> will give you - errors because other ports also share the same subdirectory. You - can call <command>rmdir</command> from <literal>@unexec</literal> to - remove only empty directories without warning.</para> - - <programlisting> -@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting> - - <para>This will neither print any error messages nor cause - <command>pkg_delete</command> to exit abnormally even if - <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is not - empty due to other ports installing some files in there.</para> - </sect3> - - <sect3> - <title>UIDs</title> - - <para>If your port requires a certain user to be on the installed - system, let the <filename>pkg/INSTALL</filename> script call - <command>pw</command> to create it automatically. Look at - <filename>net/cvsup-mirror</filename> for an example.</para> - - <para>If your port must use the same user/group ID number when it is - installed a binary package as when it was compiled, then you must - choose a free UID from 50 to 99 and register it below. Look at - <filename>japanese/Wnn</filename> for an example.</para> - - <para>Make sure you do not use a UID already used by the system or - other ports. This is the current list of UIDs between 50 and - 99.</para> - - <programlisting> -majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent -cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent -gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh -uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico -xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent -pop:*:68:6:Post Office Owner (popper):/nonexistent:/nonexistent -wnn:*:69:7:Wnn:/nonexistent:/nonexistent -ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent -pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh -ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent -alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent -qmaill:*:83:81:QMail user:/var/qmail:/nonexistent -qmaild:*:82:81:QMail user:/var/qmail:/nonexistent -qmailq:*:85:82:QMail user:/var/qmail:/nonexistent -qmails:*:87:82:QMail user:/var/qmail:/nonexistent -qmailp:*:84:81:QMail user:/var/qmail:/nonexistent -qmailr:*:86:82:QMail user:/var/qmail:/nonexistent -msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh -mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin</programlisting> - - <para>Please include a notice when you submit a port (or an upgrade) - that reserves a new UID or GID in this range. This allows us to - keep the list of reserved IDs up to date.</para> - </sect3> - - <sect3> - <title>Do things rationally</title> - - <para>The <filename>Makefile</filename> should do things simply and - reasonably. If you can make it a couple of lines shorter or more - readable, then do so. Examples include using a make - <literal>.if</literal> construct instead of a shell - <literal>if</literal> construct, not redefining - <maketarget>do-extract</maketarget> if you can redefine - <makevar>EXTRACT*</makevar> instead, and using - <makevar>GNU_CONFIGURE</makevar> instead of <literal>CONFIGURE_ARGS - += --prefix=${PREFIX}</literal>.</para> - </sect3> - - <sect3> - <title>Respect <makevar>CFLAGS</makevar></title> - - <para>The port should respect the <makevar>CFLAGS</makevar> variable. - If it does not, please add <literal>NO_PACKAGE=ignores - cflags</literal> to the <filename>Makefile</filename>.</para> - </sect3> - - <sect3> - <title>Configuration files</title> - - <para>If your port requires some configuration files in - <filename><makevar>PREFIX</makevar>/etc</filename>, do - <emphasis>not</emphasis> just install them and list them in - <filename>pkg/PLIST</filename>. That will cause - <command>pkg_delete</command> to delete files carefully edited by - the user and a new installation to wipe them out.</para> - - <para>Instead, install sample files with a suffix - (<filename><replaceable>filename</replaceable>.sample</filename> - will work well) and print out a <link - linkend="porting-message">message</link> pointing out that the - user has to copy and edit the file before the software can be made - to work.</para> - </sect3> - - <sect3> - <title>Portlint</title> - - <para>Do check your work with <link - linkend="porting-portlint"><command>portlint</command></link> - before you submit or commit it.</para> - </sect3> - - <sect3> - <title>Feedback</title> - - <para>Do send applicable changes/patches to the original - author/maintainer for inclusion in next release of the code. This - will only make your job that much easier for the next - release.</para> - </sect3> - - <sect3> - <title>Miscellanea</title> - - <para>The files <filename>pkg/DESCR</filename>, - <filename>pkg/COMMENT</filename>, and <filename>pkg/PLIST</filename> - should each be double-checked. If you are reviewing a port and feel - they can be worded better, do so.</para> - - <para>Do not copy more copies of the GNU General Public License into - our system, please.</para> - - <para>Please be careful to note any legal issues! Do not let us - illegally distribute software!</para> - </sect3> - - <sect3> - <title>If you are stuck…</title> - - <para>Do look at existing examples and the - <filename>bsd.port.mk</filename> file before asking us questions! - <!-- smiley --><emphasis>;)</emphasis></para> - - <para>Do ask us questions if you have any trouble! Do not just beat - your head against a wall! <!-- smiley - --><emphasis>:)</emphasis></para> - </sect3> - </sect2> - - <sect2 id="porting-samplem"> - <title>A Sample <filename>Makefile</filename></title> - - <para>Here is a sample <filename>Makefile</filename> that you can use to - create a new port. Make sure you remove all the extra comments (ones - between brackets)!</para> - - <para>It is recommended that you follow this format (ordering of - variables, empty lines between sections, etc.). This format is - designed so that the most important information is easy to locate. We - recommend that you use <link - linkend="porting-portlint">portlint</link> to check the - <filename>Makefile</filename>.</para> - - <programlisting> -[the header...just to make it easier for us to identify the ports.] -# New ports collection makefile for: xdvi -[the version required header should updated when upgrading a port.] -# Version required: pl18 [things like "1.5alpha" are fine here too] -[this is the date when the first version of this Makefile was created. -Never change this when doing an update of the port.] -# Date created: 26 May 1995 -[this is the person who did the original port to FreeBSD, in particular, the -person who wrote the first version of this Makefile. Remember, this should -not be changed when upgrading the port later.] -# Whom: Satoshi Asami <asami@FreeBSD.org> -# -# $Id$ -[ ^^^^ This will be automatically replaced with RCS ID string by CVS -when it is committed to our repository.] -# - -[section to describe the port itself and the master site - DISTNAME - is always first, followed by PKGNAME (if necessary), CATEGORIES, - and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. - After those, one of EXTRACT_SUFX or DISTFILES can be specified too.] -DISTNAME= xdvi -PKGNAME= xdvi-pl18 -CATEGORIES= print -[do not forget the trailing slash ("/")! - if you are not using MASTER_SITE_* macros] -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications -[set this if the source is not in the standard ".tar.gz" form] -EXTRACT_SUFX= .tar.Z - -[section for distributed patches -- can be empty] -PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ -PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz - -[maintainer; *mandatory*! This is the person (preferably with commit - privileges) who a user can contact for questions and bug reports - this - person should be the porter or someone who can forward questions to the - original porter reasonably promptly. If you really do not want to have - your address here, set it to "ports@FreeBSD.org".] -MAINTAINER= asami@FreeBSD.org - -[dependencies -- can be empty] -RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript -LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm - -[this section is for other standard bsd.port.mk variables that do not - belong to any of the above] -[If it asks questions during configure, build, install...] -IS_INTERACTIVE= yes -[If it extracts to a directory other than ${DISTNAME}...] -WRKSRC= ${WRKDIR}/xdvi-new -[If the distributed patches were not made relative to ${WRKSRC}, you - may need to tweak this] -PATCH_DIST_STRIP= -p1 -[If it requires a "configure" script generated by GNU autoconf to be run] -GNU_CONFIGURE= yes -[If it requires GNU make, not /usr/bin/make, to build...] -USE_GMAKE= yes -[If it is an X application and requires "xmkmf -a" to be run...] -USE_IMAKE= yes -[et cetera.] - -[non-standard variables to be used in the rules below] -MY_FAVORITE_RESPONSE= "yeah, right" - -[then the special rules, in the order they are called] -pre-fetch: - i go fetch something, yeah - -post-patch: - i need to do something after patch, great - -pre-install: - and then some more stuff before installing, wow - -[and then the epilogue] -.include <bsd.port.mk></programlisting> - </sect2> - - <sect2 id="porting-autoplist"> - <title>Automated package list creation</title> - - <para>First, make sure your port is almost complete, with only - <filename>PLIST</filename> missing. Create an empty - <filename>PLIST</filename>.</para> - - <screen>&prompt.root; <userinput>touch PLIST</userinput></screen> - - <para>Next, create a new set of directories which your port can be - installed, and install any dependencies.</para> - - <screen>&prompt.root; <userinput>mtree -U -f /etc/mtree/BSD.local.dist -d -e -p /var/tmp/<replaceable>port-name</replaceable></userinput> -&prompt.root; <userinput>make depends PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen> - - <para>Store the directory structure in a new file.</para> - - <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) > OLD-DIRS</userinput></screen> - - <para>If your port honours <makevar>PREFIX</makevar> (which it should) - you can then install the port and create the package list.</para> - - <screen>&prompt.root; <userinput>make install PREFIX=/var/tmp</userinput> -&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) > pkg/PLIST</userinput></screen> - - <para>You must also add any newly created directories to the packing - list.</para> - - <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm#' >> pkg/PLIST</replaceable></userinput></screen> - - <para>Finally, you need to tidy up the packing list by hand. I lied - when I said this was all automated. Manual pages should be listed in - the port's <filename>Makefile</filename> under - <makevar>MAN<replaceable>n</replaceable></makevar>, and not in the - package list. User configuration files should be removed, or - installed as - <filename><replaceable>filename</replaceable>.sample</filename>. Any - libraries installed by the port should be listed as specified in the - <link linkend="porting-ldconfig">ldconfig</link> section.</para> - </sect2> - - <sect2 id="porting-pkgname"> - <title>Package Names</title> - - <para>The following are the conventions you should follow in naming your - packages. This is to have our package directory easy to scan, as - there are already lots and lots of packages and users are going to - turn away if they hurt their eyes!</para> - - <para>The package name should look like - <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para> - - <para>If your <makevar>DISTNAME</makevar> does not look like that, set - <makevar>PKGNAME</makevar> to something in that format.</para> - - <orderedlist> - <listitem> - <para>FreeBSD strives to support the native language of its users. - The <replaceable>language-</replaceable> part should be a two - letter abbreviation of the natural language defined by ISO-639 if - the port is specific to a certain language. Examples are - <literal>ja</literal> for Japanese, <literal>ru</literal> for - Russian, <literal>vi</literal> for Vietnamese, - <literal>zh</literal> for Chinese, <literal>ko</literal> for - Korean and <literal>de</literal> for German.</para> - </listitem> - - <listitem> - <para>The <filename>name</filename> part should be all lowercases, - except for a really large package (with lots of programs in it). - Things like XFree86 (yes there really is a port of it, check it - out) and ImageMagick fall into this category. Otherwise, convert - the name (or at least the first letter) to lowercase. If the - capital letters are important to the name (for example, with - one-letter names like <literal>R</literal> or - <literal>V</literal>) you may use capital letters at your - discretion. There is a tradition of naming Perl 5 modules by - prepending <literal>p5-</literal> and converting the double-colon - separator to a hyphen; for example, the - <literal>Data::Dumper</literal> module becomes - <literal>p5-Data-Dumper</literal>. If the software in question - has numbers, hyphens, or underscores in its name, you may include - them as well (like <literal>kinput2</literal>).</para> - </listitem> - - <listitem> - <para>If the port can be built with different <link - linkend="porting-masterdir">hardcoded defaults</link> (usually - part of the directory name in a family of ports), the - <replaceable>-compiled.specifics</replaceable> part should state - the compiled-in defaults (the hyphen is optional). Examples are - papersize and font units.</para> - </listitem> - - <listitem> - <para>The version string should be a period-separated list of - integers and single lowercase alphabetics. The only exception is - the string <literal>pl</literal> (meaning `patchlevel'), which can - be used <emphasis>only</emphasis> when there are no major and - minor version numbers in the software.</para> - </listitem> - </orderedlist> - - <para>Here are some (real) examples on how to convert a - <makevar>DISTNAME</makevar> into a suitable - <makevar>PKGNAME</makevar>:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>Distribution Name</entry> - <entry>Package Name</entry> - <entry>Reason</entry> - </row> - </thead> - - <tbody> - <row> - <entry>mule-2.2.2.</entry> - <entry>mule-2.2.2</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>XFree86-3.1.2</entry> - <entry>XFree86-3.1.2</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>EmiClock-1.0.2</entry> - <entry>emiclock-1.0.2</entry> - <entry>No uppercase names for single programs</entry> - </row> - - <row> - <entry>gmod1.4</entry> - <entry>gmod-1.4</entry> - <entry>Need a hyphen before version numbers</entry> - </row> - - <row> - <entry>xmris.4.0.2</entry> - <entry>xmris-4.0.2</entry> - <entry>Need a hyphen before version numbers</entry> - </row> - - <row> - <entry>rdist-1.3alpha</entry> - <entry>rdist-1.3a</entry> - <entry>No strings like <literal>alpha</literal> - allowed</entry> - </row> - - <row> - <entry>es-0.9-beta1</entry> - <entry>es-0.9b1</entry> - <entry>No strings like <literal>beta</literal> - allowed</entry> - </row> - - <row> - <entry>v3.3beta021.src</entry> - <entry>tiff-3.3</entry> - <entry>What the heck was that anyway?</entry> - </row> - - <row> - <entry>tvtwm</entry> - <entry>tvtwm-pl11</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>piewm</entry> - <entry>piewm-1.0</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>xvgr-2.10pl1</entry> - <entry>xvgr-2.10.1</entry> - <entry><literal>pl</literal> allowed only when no - major/minor version numbers</entry> - </row> - - <row> - <entry>gawk-2.15.6</entry> - <entry>ja-gawk-2.15.6</entry> - <entry>Japanese language version</entry> - </row> - - <row> - <entry>psutils-1.13</entry> - <entry>psutils-letter-1.13</entry> - <entry>Papersize hardcoded at package build time</entry> - </row> - - <row> - <entry>pkfonts</entry> - <entry>pkfonts300-1.0</entry> - <entry>Package for 300dpi fonts</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If there is absolutely no trace of version information in the - original source and it is unlikely that the original author will ever - release another version, just set the version string to - <literal>1.0</literal> (like the piewm example above). Otherwise, ask - the original author or use the date string - (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the version.</para> - </sect2> - - <sect2 id="porting-categories"> - <title>Categories</title> - - <para>As you already know, ports are classified in several categories. - But for this to work, it is important that porters and users understand - what each category and how we decide what to put in each - category.</para> - - <sect3> - <title>Current list of categories</title> - - <para>First, this is the current list of port categories. Those - marked with an asterisk (<literal>*</literal>) are - <emphasis>virtual</emphasis> categories—those that do not have - a corresponding subdirectory in the ports tree.</para> - - <note> - <para>For non-virtual categories, you will find a one-line - description in the <filename>pkg/COMMENT</filename> file in that - subdirectory (e.g., - <filename>archivers/pkg/COMMENT</filename>).</para> - </note> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Category</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>afterstep*</filename></entry> - <entry>Ports to support AfterStep window manager</entry> - </row> - - <row> - <entry><filename>archivers</filename></entry> - <entry>Archiving tools.</entry> - </row> - - <row> - <entry><filename>astro</filename></entry> - <entry>Astronomical ports.</entry> - </row> - - <row> - <entry><filename>audio</filename></entry> - <entry>Sound support.</entry> - </row> - - <row> - <entry><filename>benchmarks</filename></entry> - <entry>Benchmarking utilities.</entry> - </row> - - <row> - <entry><filename>biology</filename></entry> - <entry>Biology-related software.</entry> - </row> - - <row> - <entry><filename>cad</filename></entry> - <entry>Computer aided design tools.</entry> - </row> - - <row> - <entry><filename>chinese</filename></entry> - <entry>Chinese language support.</entry> - </row> - - <row> - <entry><filename>comms</filename></entry> - <entry>Communication software. Mostly software to talk to - your serial port.</entry> - </row> - - <row> - <entry><filename>converters</filename></entry> - <entry>Character code converters.</entry> - </row> - - <row> - <entry><filename>databases</filename></entry> - <entry>Databases.</entry> - </row> - - <row> - <entry><filename>deskutils</filename></entry> - <entry>Things that used to be on the desktop before - computers were invented.</entry> - </row> - - <row> - <entry><filename>devel</filename></entry> - <entry>Development utilities. Do not put libraries here just - because they are libraries—unless they truly do not - belong to anywhere else, they should not be in this - category.</entry> - </row> - - <row> - <entry><filename>editors</filename></entry> - <entry>General editors. Specialized editors go in the section - for those tools (e.g., a mathematical-formula editor will go - in <filename>math</filename>).</entry> - </row> - - <row> - <entry><filename>elisp</filename></entry> - <entry>Emacs-lisp ports.</entry> - </row> - - <row> - <entry><filename>emulators</filename></entry> - <entry>Emulators for other operating systems. Terminal - emulators do <emphasis>not</emphasis> belong - here—X-based ones should go to - <filename>x11</filename> and text-based ones to either - <filename>comms</filename> or <filename>misc</filename>, - depending on the exact functionality.</entry> - </row> - - <row> - <entry><filename>ftp</filename></entry> - <entry>FTP client and server utilities. If your - port speaks both FTP and HTTP, put it in - <filename>ftp</filename> with a secondary - category of <filename>www</filename>.</entry> - </row> - - <row> - <entry><filename>games</filename></entry> - <entry>Games.</entry> - </row> - - <row> - <entry><filename>german</filename></entry> - <entry>German language support.</entry> - </row> - - <row> - <entry><filename>graphics</filename></entry> - <entry>Graphics utilities.</entry> - </row> - - <row> - <entry><filename>irc</filename></entry> - <entry>Internet Chat Relay utilities.</entry> - </row> - - <row> - <entry><filename>japanese</filename></entry> - <entry>Japanese language support.</entry> - </row> - - <row> - <entry><filename>java</filename></entry> - <entry>Java language support.</entry> - </row> - - <row> - <entry><filename>kde*</filename></entry> - <entry>Ports that form the K Desktop Environment - (kde).</entry> - </row> - - <row> - <entry><filename>korean</filename></entry> - <entry>Korean language support.</entry> - </row> - - <row> - <entry><filename>lang</filename></entry> - <entry>Programming languages.</entry> - </row> - - <row> - <entry><filename>mail</filename></entry> - <entry>Mail software.</entry> - </row> - - <row> - <entry><filename>math</filename></entry> - <entry>Numerical computation software and other utilities - for mathematics.</entry> - </row> - - <row> - <entry><filename>mbone</filename></entry> - <entry>MBone applications.</entry> - </row> - - <row> - <entry><filename>misc</filename></entry> - <entry>Miscellaneous utilities—basically things that - does not belong to anywhere else. This is the only category - that should not appear with any other non-virtual category. - If you have <literal>misc</literal> with something else in - your <makevar>CATEGORIES</makevar> line, that means you can - safely delete <literal>misc</literal> and just put the port - in that other subdirectory!</entry> - </row> - - <row> - <entry><filename>net</filename></entry> - <entry>Miscellaneous networking software.</entry> - </row> - - <row> - <entry><filename>news</filename></entry> - <entry>USENET news software.</entry> - </row> - - <row> - <entry><filename>offix*</filename></entry> - <entry>Ports from the OffiX suite.</entry> - </row> - - <row> - <entry><filename>palm</filename></entry> - <entry>Software support for the 3Com Palm(tm) series.</entry> - </row> - - <row> - <entry><filename>perl5*</filename></entry> - <entry>Ports that require perl version 5 to run.</entry> - </row> - - <row> - <entry><filename>plan9*</filename></entry> - <entry>Various programs from Plan9.</entry> - </row> - - <row> - <entry><filename>print</filename></entry> - <entry>Printing software. Desktop publishing tools - (previewers, etc.) belong here too.</entry> - </row> - - <row> - <entry><filename>python*</filename></entry> - <entry>Software written in python.</entry> - </row> - - <row> - <entry><filename>russian</filename></entry> - <entry>Russian language support.</entry> - </row> - - <row> - <entry><filename>security</filename></entry> - <entry>Security utilities.</entry> - </row> - - <row> - <entry><filename>shells</filename></entry> - <entry>Command line shells.</entry> - </row> - - <row> - <entry><filename>sysutils</filename></entry> - <entry>System utilities.</entry> - </row> - - <row> - <entry><filename>tcl75*</filename></entry> - <entry>Ports that use tcl version 7.5 to run.</entry> - </row> - - <row> - <entry><filename>tcl76*</filename></entry> - <entry>Ports that use tcl version 7.6 to run.</entry> - </row> - - <row> - <entry><filename>tcl80*</filename></entry> - <entry>Ports that use tcl version 8.0 to run.</entry> - </row> - - <row> - <entry><filename>tcl81*</filename></entry> - <entry>Ports that use tcl version 8.1 to run.</entry> - </row> - - <row> - <entry><filename>textproc</filename></entry> - <entry>Text processing utilities. It does not include - desktop publishing tools, which go to print/.</entry> - </row> - - <row> - <entry><filename>tk41*</filename></entry> - <entry>Ports that use tk version 4.1 to run.</entry> - </row> - - <row> - <entry><filename>tk42*</filename></entry> - <entry>Ports that use tk version 4.2 to run.</entry> - </row> - - <row> - <entry><filename>tk80*</filename></entry> - <entry>Ports that use tk version 8.0 to run.</entry> - </row> - - <row> - <entry><filename>tk81*</filename></entry> - <entry>Ports that use tk version 8.1 to run.</entry> - </row> - - <row> - <entry><filename>vietnamese</filename></entry> - <entry>Vietnamese language support.</entry> - </row> - - <row> - <entry><filename>windowmaker*</filename></entry> - <entry>Ports to support the WindowMaker window - manager</entry> - </row> - - <row> - <entry><filename>www</filename></entry> - <entry>Software related to the World Wide Web. HTML language - support belong here too.</entry> - </row> - - <row> - <entry>x11</entry> - <entry>The X window system and friends. This category is only - for software that directly support the window system. Do not - put regular X applications here. If your port is an X - application, define <makevar>USE_XLIB</makevar> (implied by - <makevar>USE_IMAKE</makevar>) and put it in appropriate - categories. Also, many of them go into other - <filename>x11-*</filename> categories (see below).</entry> - </row> - - <row> - <entry><filename>x11-clocks</filename></entry> - <entry>X11 clocks.</entry> - </row> - - <row> - <entry><filename>x11-fm</filename></entry> - <entry>X11 file managers.</entry> - </row> - - <row> - <entry><filename>x11-fonts</filename></entry> - <entry>X11 fonts and font utilities.</entry> - </row> - - <row> - <entry><filename>x11-servers</filename></entry> - <entry>X11 servers.</entry> - </row> - - <row> - <entry><filename>x11-toolkits</filename></entry> - <entry>X11 toolkits.</entry> - </row> - - <row> - <entry><filename>x11-wm</filename></entry> - <entry>X11 window managers.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - - <sect3> - <title>Choosing the right category</title> - - <para>As many of the categories overlap, you often have to choose - which of the categories should be the primary category of your port. - There are several rules that govern this issue. Here is the list of - priorities, in decreasing order of precedence.</para> - - <itemizedlist> - <listitem> - <para>Language specific categories always come first. For - example, if your port installs Japanese X11 fonts, then your - <makevar>CATEGORIES</makevar> line would read <literal>japanese - x11-fonts</literal>.</para> - </listitem> - - <listitem> - <para>Specific categories win over less-specific ones. For - instance, an HTML editor should be listed as <literal>www - editors</literal>, not the other way around. Also, you do not - need to list <literal>net</literal> when the port belongs to - either of <literal>irc</literal>, <literal>mail</literal>, - <literal>mbone</literal>, <literal>news</literal>, - <literal>security</literal>, or <literal>www</literal>.</para> - </listitem> - - <listitem> - <para><literal>x11</literal> is used as a secondary category only - when the primary category is a natural language. In particular, - you should not put <literal>x11</literal> in the category line - for X applications.</para> - </listitem> - - <listitem> - <para>If your port truly does not belong anywhere else, put it in - <literal>misc</literal>.</para> - </listitem> - </itemizedlist> - - <para>If you are not sure about the category, please put a comment to - that effect in your <command>send-pr</command> submission so we can - discuss it before import it. (If you are a committer, send a note - &a.ports; so we can discuss it first—too often new ports are - imported to a wrong category only to be moved right away.)</para> - </sect3> - </sect2> - - <sect2> - <title>Changes to this document and the ports system</title> - - <para>If you maintain a lot of ports, you should consider following the - &a.ports;. Important changes to the way ports work will be announced - there. You can always find more detailed information on the latest - changes by looking at <ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk"> the - bsd.port.mk CVS log</ulink>.</para> - </sect2> - - <sect2> - <title>That is It, Folks!</title> - - <para>Boy, this sure was a long tutorial, wasn't it? Thanks for - following us to here, really.</para> - - <para>Well, now that you know how to do a port, let us go at it and - convert everything in the world into ports! That is the easiest way to - start contributing to the FreeBSD Project! <!-- smiley - --><emphasis>:)</emphasis></para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> diff --git a/en/handbook/ppp-and-slip/chapter.sgml b/en/handbook/ppp-and-slip/chapter.sgml deleted file mode 100644 index 1a3c352e3a..0000000000 --- a/en/handbook/ppp-and-slip/chapter.sgml +++ /dev/null @@ -1,2488 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.13 1999-08-05 20:48:21 nik Exp $ ---> - -<chapter id="ppp-and-slip"> - <title>PPP and SLIP</title> - - <para>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: <emphasis>user</emphasis> (sometimes - referred to as <emphasis>iijppp</emphasis>) and - <emphasis>kernel</emphasis>. The procedures for configuring both types of - PPP, and for setting up SLIP are described in this chapter.</para> - - <sect1 id="userppp"> - <title>Setting up User PPP</title> - - <para>User PPP was introduced to FreeBSD in release 2.0.5 as an addition - to the existing kernel implementation of PPP. So, what is different - about this new PPP that warrants its addition? To quote from the manual - page:</para> - - <blockquote> - <para>This is a user process PPP software package. Normally, PPP is - implemented as a part of the kernel (e.g. as managed by - <command>pppd</command>) and it is thus somewhat hard to debug and/or - modify its behavior. However, in this implementation PPP is done as a - user process with the help of the tunnel device driver - (<devicename>tun</devicename>).</para> - </blockquote> - - <para>In essence, this means that rather than running a PPP daemon, the - ppp program can be run as and when desired. No PPP interface needs to - be compiled into the kernel, as the program can use the generic tunnel - device to get data into and out of the kernel.</para> - - <para>From here on out, user ppp will be referred to simply as ppp unless - a distinction needs to be made between it and any other PPP - client/server software such as <command>pppd</command>. Unless - otherwise stated, all commands in this section should be executed as - root.</para> - - <para>There are a large number of enhancements in version 2 of ppp. You - can discover what version you have by running ppp with no arguments and - typing <command>show version</command> at the prompt. It is a simple - matter to upgrade to the latest version of ppp (under any version of - FreeBSD) by downloading the latest archive via <ulink - url="http://www.Awfulhak.org/ppp.html">www.Awfulhak.org</ulink>.</para> - - <sect2> - <title>Before you start</title> - - <para>This document assumes you are in roughly this position:</para> - - <para>You have an account with an Internet Service Provider (ISP) which - lets you use PPP. Further, you have a modem (or other device) - connected and configured correctly which allows you to connect to your - ISP.</para> - - <para>You are going to need the following information to hand:</para> - - <itemizedlist> - <listitem> - <para>Your ISPs phone number(s).</para> - </listitem> - - <listitem> - <para>Your login name and password. This can be either a regular - unix style login/password pair, or a PPP PAP or CHAP - login/password pair.</para> - </listitem> - - <listitem> - <para>The IP addresses of one or more nameservers. Normally, you - will be given two IP numbers. You <emphasis>must</emphasis> have - this information for <application>PPP</application> version 1.x - unless you run your own nameserver. From version 2 onwards, - <application>PPP</application> supports nameserver address - negotiation. If your ISP supports this, then using the command - <command>enable dns</command> in your config file will tell - <application>PPP</application> to set the nameservers for - you.</para> - </listitem> - </itemizedlist> - - <para>The following information may have been supplied by your ISP, but - is not strictly necessary:</para> - - <itemizedlist> - <listitem> - <para>The IP address of your ISP's gateway. The gateway is the - machine to which you will connect and will be set up as your - <emphasis>default route</emphasis>. If your ISP hasn't given you - this number, we can make one up and your ISP's PPP server will - tell us the correct value when we connect.</para> - - <para>This IP number is referred to as <literal>HISADDR</literal> - by ppp.</para> - </listitem> - - <listitem> - <para>Your ISP's netmask. If your ISP hasn't given you this - information, you can safely use a netmask of <hostid - role="netmask">255.255.255.0</hostid>.</para> - - <para>If your ISP allocates you a static IP address and hostname - then you can enter this information. Otherwise, we simply let the - peer assign whatever IP number it sees fit.</para> - </listitem> - </itemizedlist> - - <para>If you do not have any of the required information, contact your - ISP and make sure they provide it to you.</para> - </sect2> - - <sect2> - <title>Building a ppp ready kernel</title> - - <para>As the description states, <command>ppp</command> uses the kernel - <devicename>tun</devicename> device. It is necessary to make sure - that your kernel has support for this device compiled in.</para> - - <para>To check this, go to your kernel compile directory - (<filename>/sys/i386/conf</filename> or - <filename>/sys/pc98/conf</filename>) and examine your kernel - configuration file. It needs to have the line - - <programlisting> -pseudo-device tun 1</programlisting> - - in it somewhere. The stock <filename>GENERIC</filename> kernel has - this as standard, so if you have not installed a custom kernel or you - do not have a <filename>/sys</filename> directory, you do not have to - change anything.</para> - - <para>If your kernel configuration file does not have this line in it, - or you need to configure more than one <devicename>tun</devicename> device (for example, if you - are setting up a server and could have 16 dialup ppp connections at - any one time then you will need to use <literal>16</literal> instead - of <literal>1</literal>), then you should add the line, re-compile, - re-install and boot the new kernel. Please refer to the <link - linkend="kernelconfig">Configuring the FreeBSD Kernel</link> section - for more information on kernel configuration.</para> - - <para>You can check how many tunnel devices your current kernel has by - typing the following:</para> - - <screen>&prompt.root; <userinput>ifconfig -a</userinput> -tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 - inet 200.10.100.1 --> 203.10.100.24 netmask 0xffffffff -tun1: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 576 -tun2: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 - inet 203.10.100.1 --> 203.10.100.20 netmask 0xffffffff -tun3: flags=8010<POINTOPOINT,MULTICAST> mtu 1500</screen> - - - <para>This case shows four tunnel devices, two of which are currently - configured and being used. It should be noted that the - <literal>RUNNING</literal> flag above indicates that the interface has - been used at some point—it is not an error if your interface - does not show up as <literal>RUNNING</literal>.</para> - - <para>If you have a kernel without the <devicename>tun</devicename> device, and you can not - rebuild it for some reason, all is not lost. You should be able to - dynamically load the code. Refer to the appropriate - &man.modload.8; and &man.lkm.4; pages for further details.</para> - - <para>You may also wish to take this opportunity to configure a - firewall. Details can be found in the <link - linkend="firewalls">Firewalls</link> section.</para> - </sect2> - - <sect2> - <title>Check the tun device</title> - - <para>Most users will only require one <devicename>tun</devicename> - device (<filename>/dev/tun0</filename>). If you have used more (i.e., - a number other than <literal>1</literal> in the - <literal>pseudo-device</literal> line in the kernel configuration - file) then alter all references to <devicename>tun0</devicename> below - to reflect whichever device number you are using.</para> - - <para>The easiest way to make sure that the - <devicename>tun0</devicename> device is configured correctly is to - re-make it. To do this, execute the following commands:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV tun0</userinput></screen> - - <para>If you require 16 tunnel devices in your kernel, you will need to - create more than just <devicename>tun0</devicename>:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV tun15</userinput></screen> - - <para>Also, to confirm that the kernel is configured correctly, the - following command should give the indicated output:</para> - - <screen>&prompt.root; <userinput>ifconfig tun0</userinput> -tun0: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 1500</screen> - - <para>The <literal>RUNNING</literal> flag may not yet be set, in which - case you will see:</para> - - <screen>&prompt.root; <userinput>ifconfig tun0</userinput> -tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500</screen> - </sect2> - - <sect2> - <title>Name Resolution Configuration</title> - - <para>The resolver is the part of the system that turns IP addresses - into hostnames and vice versa. It can be configured to look for maps - that describe IP to hostname mappings in one of two places. The first - is a file called <filename>/etc/hosts</filename> (<command>man 5 - hosts</command>). The second is the Internet Domain Name Service - (DNS), a distributed data base, the discussion of which is beyond the - scope of this document.</para> - - <para>This section describes briefly how to configure your - resolver.</para> - - <para>The resolver is a set of system calls that do the name mappings, - but you have to tell them where to find their information. You do - this by first editing the file <filename>/etc/host.conf</filename>. - Do <emphasis>not</emphasis> call this file - <filename>/etc/hosts.conf</filename> (note the extra - <literal>s</literal>) as the results can be confusing.</para> - - <sect3> - <title>Edit the <filename>/etc/host.conf</filename> file</title> - - <para>This file should contain the following two lines (in this - order):</para> - - <programlisting> -hosts -bind</programlisting> - - <para>These instructs the resolver to first look in the file - <filename>/etc/hosts</filename>, and then to consult the DNS if the - name was not found.</para> - </sect3> - - <sect3> - <title>Edit the <filename>/etc/hosts</filename>(5) file</title> - - <para>This file should contain the IP addresses and names of machines - on your network. At a bare minimum it should contain entries for - the machine which will be running ppp. Assuming that your machine - is called <hostid role="fqdn">foo.bar.com</hostid> with the IP - address <hostid role="ipaddr">10.0.0.1</hostid>, - <filename>/etc/hosts</filename> should contain:</para> - - <programlisting> -127.0.0.1 localhost -10.0.0.1 foo.bar.com foo</programlisting> - - <para>The first line defines the alias <hostid>localhost</hostid> as a - synonym for the current machine. Regardless of your own IP address, - the IP address for this line should always be <hostid - role="ipaddr">127.0.0.1</hostid>. The second line maps the name - <hostid role="fqdn">foo.bar.com</hostid> (and the shorthand - <hostid>foo</hostid>) to the IP address <hostid - role="ipaddr">10.0.0.1</hostid>.</para> - - <para>If your provider allocates you a static IP address and name, - then use these in place of the <hostid - role="ipaddr">10.0.0.1</hostid> entry.</para> - </sect3> - - <sect3> - <title>Edit the <filename>/etc/resolv.conf</filename> file</title> - - <para><filename>/etc/resolv.conf</filename> tells the resolver how to - behave. If you are running your own DNS, you may leave this file - empty. Normally, you will need to enter the following - line(s):</para> - - <programlisting> -nameserver <replaceable>x.x.x.x</replaceable> -nameserver <replaceable>y.y.y.y</replaceable> -domain <replaceable>bar.com</replaceable></programlisting> - - <para>The <hostid - role="ipaddr"><replaceable>x.x.x.x</replaceable></hostid> and - <hostid role="ipaddr"><replaceable>y.y.y.y</replaceable></hostid> - addresses are those given to you by your ISP. Add as many - <literal>nameserver</literal> lines as your ISP provides. The - <literal>domain</literal> line defaults to your hostname's domain, - and is probably unnecessary. Refer to the - <filename>resolv.conf</filename> manual page for details of other - possible entries in this file.</para> - - <para>If you are running PPP version 2 or greater, the <command>enable - dns</command> command will tell PPP to request that your ISP - confirms the nameserver values. If your ISP supplies different - addresses (or if there are no nameserver lines in - <filename>/etc/resolv.conf</filename>), PPP will rewrite the file - with the ISP-supplied values.</para> - </sect3> - </sect2> - - <sect2> - <title><command>ppp</command> Configuration</title> - - <para>Both user ppp and <command>pppd</command> (the kernel level - implementation of PPP) use configuration files located in the - <filename>/etc/ppp</filename> directory. The sample configuration - files provided are a good reference for user ppp, so don't delete - them.</para> - - <para>Configuring <command>ppp</command> requires that you edit a number - of files, depending on your requirements. What you put in them - depends to some extent on whether your ISP allocates IP addresses - statically (i.e., you get given one IP address, and always use that - one) or dynamically (i.e., your IP address can be different for each - PPP session).</para> - - <sect3 id="userppp-staticIP"> - <title>PPP and Static IP addresses</title> - - <para>You will need to create a configuration file called - <filename>/etc/ppp/ppp.conf</filename>. It should look similar to - the example below.</para> - - <note> - <para>Lines that end in a <literal>:</literal> start in the first - column, all other lines should be indented as shown using spaces - or tabs.</para> - </note> - - <programlisting> -1 default: -2 set device /dev/cuaa0 -3 set speed 115200 -4 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK \\dATDT\\TTIMEOUT 40 CONNECT" -5 provider: -6 set phone "(0123) 456 7890" -7 set login "TIMEOUT 10 \"\" \"\" gin:--gin: foo word: bar col: ppp" -8 set timeout 300 -9 set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.0 0.0.0.0 -10 add default HISADDR -11 enable dns</programlisting> - - <para>Do not include the line numbers, they are just for reference in - this discussion.</para> - - <variablelist> - <varlistentry> - <term>Line 1:</term> - - <listitem> - <para>Identifies the default entry. Commands in this entry are - executed automatically when ppp is run.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 2:</term> - - <listitem> - <para>Identifies the device to which the modem is connected. - <devicename>COM1:</devicename> is - <filename>/dev/cuaa0</filename> and - <devicename>COM2:</devicename> is - <filename>/dev/cuaa1</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 3:</term> - - <listitem> - <para>Sets the speed you want to connect at. If 115200 doesn't - work (it should with any reasonably new modem), try 38400 - instead.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 4:</term> - - <listitem> - <para>The dial string. User PPP uses an expect-send syntax - similar to the &man.chat.8; program. Refer to the - manual page for information on the features of this - language.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 5:</term> - - <listitem> - <para>Identifies an entry for a provider called - “provider”.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 6:</term> - - <listitem> - <para>Sets the phone number for this provider. Multiple phone - numbers may be specified using the <literal>:</literal> or - <literal>|</literal> character as a separator. The difference - between these separators is described in &man.ppp.8;. - To summarize, if you want to rotate through the numbers, use - the <literal>:</literal>. If you want to always attempt to - dial the first number first and only use the other numbers if - the first number fails, use the <literal>|</literal>. Always - quote the entire set of phone numbers as shown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 7:</term> - - <listitem> - <para>The login string is of the same chat-like syntax as the - dial string. In this example, the string works for a service - whose login session looks like this:</para> - - <screen>J. Random Provider -login: <replaceable>foo</replaceable> -password: <replaceable>bar</replaceable> -protocol: ppp</screen> - - <para>You will need to alter this script to suit your own needs. - When you write this script for the first time, you should - enable “chat” logging to ensure that the - conversation is going as expected.</para> - - <para>If you're using PAP or CHAP, there will be no login at - this point, so your login string can be left blank. See <link - linkend="userppp-PAPnCHAP">PAP and CHAP - authentication</link> for further details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 8:</term> - - <listitem> - <para>Sets the default timeout (in seconds) for the connection. - Here, the connection will be closed automatically after 300 - seconds of inactivity. If you never want to timeout, set this - value to zero.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 9:</term> - - <listitem> - <para>Sets the interface addresses. The string - <replaceable>x.x.x.x</replaceable> should be replaced by the - IP address that your provider has allocated to you. The - string <replaceable>y.y.y.y</replaceable> should be replaced - by the IP address that your ISP indicated for their gateway - (the machine to which you connect). If your ISP hasn't given - you a gateway address, use <hostid - role="netmask">10.0.0.2/0</hostid>. If you need to use a - “guessed” address, make sure that you create an - entry in <filename>/etc/ppp/ppp.linkup</filename> as per the - instructions for <link linkend="userppp-dynamicIP">PPP and - Dynamic IP addresses</link>. If this line is omitted, - <command>ppp</command> cannot run in <option>-auto</option> or - <option>-dynamic</option> mode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 10:</term> - - <listitem> - <para>Adds a default route to your ISPs gateway. The special - word <literal>HISADDR</literal> is replaced with the gateway - address specified on line 9. It is important that this line - appears after line 9, otherwise <literal>HISADDR</literal> - will not yet be initialized.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 11:</term> - - <listitem> - <para>This line tells PPP to ask your ISP to confirm that your - nameserver addresses are correct. If your ISP supports this - facility, PPP can then update - <filename>/etc/resolv.conf</filename> with the correct - nameserver entries.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>It is not necessary to add an entry to - <filename>ppp.linkup</filename> when you have a static IP address as - your routing table entries are already correct before you connect. - You may however wish to create an entry to invoke programs after - connection. This is explained later with the sendmail - example.</para> - - <para>Example configuration files can be found in the - <filename>/etc/ppp</filename> directory.</para> - </sect3> - - <sect3 id="userppp-dynamicIP"> - <title>PPP and Dynamic IP addresses</title> - - <para>If your service provider does not assign static IP numbers, - <command>ppp</command> can be configured to negotiate the local and - remote addresses. This is done by “guessing” an IP - number and allowing <command>ppp</command> to set it up correctly - using the IP Configuration Protocol (IPCP) after connecting. The - <filename>ppp.conf</filename> configuration is the same as <link - linkend="userppp-staticIP">PPP and Static IP addresses</link>, - with the following change:</para> - - <programlisting> -9 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0</programlisting> - - <para>Again, do not include the line numbers, they are just for - reference in this discussion. Indentation of at least one space is - required.</para> - - <variablelist> - <varlistentry> - <term>Line 9:</term> - - <listitem> - <para>The number after the <literal>/</literal> character is the - number of bits of the address that ppp will insist on. You - may wish to use IP numbers more appropriate to your - circumstances, but the above example will always work.</para> - - <para>The last argument (<literal>0.0.0.0</literal>) tells PPP - to negotiate using address <hostid - role="ipaddr">0.0.0.0</hostid> rather than <hostid - role="ipaddr">10.0.0.1</hostid>. Do not use - <literal>0.0.0.0</literal> as the first argument to - <command>set ifaddr</command> as it prevents PPP from setting - up an initial route in <option>-auto</option> mode.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>If you are running version 1.x of PPP, you will also need to - create an entry in <filename>/etc/ppp/ppp.linkup</filename>. - <filename>ppp.linkup</filename> is used after a connection has been - established. At this point, <command>ppp</command> will know what - IP addresses should <emphasis>really</emphasis> be used. The - following entry will delete the existing bogus routes, and create - correct ones:</para> - - <programlisting> -1 provider: -2 delete ALL -3 add 0 0 HISADDR</programlisting> - - <variablelist> - <varlistentry> - <term>Line 1:</term> - - <listitem> - <para>On establishing a connection, <command>ppp</command> will - look for an entry in <filename>ppp.linkup</filename> according - to the following rules: First, try to match the same label as - we used in <filename>ppp.conf</filename>. If that fails, look - for an entry for the IP number of our gateway. This entry is - a four-octet IP style label. If we still haven't found an - entry, look for the <literal>MYADDR</literal> entry.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 2:</term> - - <listitem> - <para>This line tells <command>ppp</command> to delete all - existing routes for the acquired tun interface (except the - direct route entry).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 3:</term> - - <listitem> - <para>This line tells <command>ppp</command> to add a default - route that points to <literal>HISADDR</literal>. - <literal>HISADDR</literal> will be replaced with the IP number - of the gateway as negotiated in the IPCP.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>See the pmdemand entry in the files - <filename>/etc/ppp/ppp.conf.sample</filename> and - <filename>/etc/ppp/ppp.linkup.sample</filename> for a detailed - example.</para> - - <para>Version 2 of PPP introduces “sticky routes”. Any - <literal>add</literal> or <literal>delete</literal> lines that - contain <literal>MYADDR</literal> or <literal>HISADDR</literal> will - be remembered, and any time the actual values of - <literal>MYADDR</literal> or <literal>HISADDR</literal> change, the - routes will be re-applied. This removes the necessity of repeating - these lines in <filename>ppp.linkup</filename>.</para> - </sect3> - - <sect3> - <title>Receiving incoming calls with <command>ppp</command></title> - - <para>This section describes setting up <command>ppp</command> in a - server role.</para> - - <para>When you configure <command>ppp</command> to receive incoming - calls on a machine connected to a LAN, you must decide if you wish - to forward packets to the LAN. If you do, you should allocate the - peer an IP number from your LAN's subnet, and use the command - - <programlisting> -enable proxy</programlisting> - - in your <filename>ppp.conf</filename> file. You should also confirm - that the <filename>/etc/rc.conf</filename> file (this file used to - be called <filename>/etc/sysconfig</filename>) contains the - following:</para> - - <programlisting> -gateway=YES</programlisting> - - <sect4> - <title>Which getty?</title> - - <para><link linkend="dialup">Configuring FreeBSD for Dialup - Services</link> provides a good description on enabling dialup - services using getty.</para> - - <para>An alternative to <command>getty</command> is <ulink - URL="http://www.leo.org/~doering/mgetty/index.html">mgetty</ulink>, - a smarter version of <command>getty</command> designed with dialup - lines in mind.</para> - - <para>The advantages of using <command>mgetty</command> is that it - actively <emphasis>talks</emphasis> to modems, meaning if port is - turned off in <filename>/etc/ttys</filename> then your modem won't - answer the phone.</para> - - <para>Later versions of <command>mgetty</command> (from 0.99beta - onwards) also support the automatic detection of PPP streams, - allowing your clients script-less access to your server.</para> - - <para>Refer to <link linkend="userppp-mgetty">Mgetty and - AutoPPP</link> for more information on - <command>mgetty</command>.</para> - </sect4> - - <sect4> - <title>PPP permissions</title> - - <para><command>ppp</command> must normally be run as user id 0. If - however you wish to allow <command>ppp</command> to run in server - mode as a normal user by executing <command>ppp</command> as - described below, that user must be given permission to run - <command>ppp</command> by adding them to the - <username>network</username> group in - <filename>/etc/group</filename>.</para> - - <para>You will also need to give them access to one or more sections - of the configuration file using the <command>allow</command> - command:</para> - - <programlisting> -allow users fred mary</programlisting> - - <para>If this command is used in the <literal>default</literal> - section, it gives the specified users access to everything.</para> - </sect4> - - <sect4> - <title>Setting up a PPP shell for dynamic-IP users</title> - - <para>Create a file called <filename>/etc/ppp/ppp-shell</filename> - containing the following:</para> - - <programlisting> -#!/bin/sh -IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'` -CALLEDAS="$IDENT" -TTY=`tty` - -if [ x$IDENT = xdialup ]; then - IDENT=`basename $TTY` -fi - -echo "PPP for $CALLEDAS on $TTY" -echo "Starting PPP for $IDENT" - -exec /usr/sbin/ppp -direct $IDENT</programlisting> - - <para>This script should be executable. Now make a symbolic link - called <filename>ppp-dialup</filename> to this script using the - following commands:</para> - - <screen>&prompt.root; <userinput>ln -s ppp-shell /etc/ppp/ppp-dialup</userinput></screen> - - <para>You should use this script as the <emphasis>shell</emphasis> - for all your dialup ppp users. This is an example from - <filename>/etc/password</filename> for a dialup PPP user with - username <username>pchilds</username>. (remember don't directly - edit the password file, use <command>vipw</command>)</para> - - <programlisting> -pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup</programlisting> - - <para>Create a <filename>/home/ppp</filename> directory that is - world readable containing the following 0 byte files - - <screen>-r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin --r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts</screen> - - which prevents <filename>/etc/motd</filename> from being - displayed.</para> - </sect4> - - <sect4> - <title>Setting up a PPP shell for static-IP users</title> - - <para>Create the <filename>ppp-shell</filename> file as above and - for each account with statically assigned IPs create a symbolic - link to <filename>ppp-shell</filename>.</para> - - <para>For example, if you have three dialup customers - <username>fred</username>, <username>sam</username>, and - <username>mary</username>, that you route class C networks for, - you would type the following:</para> - - <screen>&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred</userinput> -&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam</userinput> -&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary</userinput></screen> - - <para>Each of these users dialup accounts should have their shell - set to the symbolic link created above. (ie. - <username>mary</username>'s shell should be - <filename>/etc/ppp/ppp-mary</filename>).</para> - </sect4> - - <sect4> - <title>Setting up ppp.conf for dynamic-IP users</title> - - <para>The <filename>/etc/ppp/ppp.conf</filename> file should contain - something along the lines of</para> - - <programlisting> -default: - set debug phase lcp chat - set timeout 0 - -ttyd0: - set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255 - enable proxy - -ttyd1: - set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255 - enable proxy</programlisting> - - <note> - <para>The indenting is important.</para> - </note> - - <para>The <literal>default:</literal> section is loaded for each - session. For each dialup line enabled in - <filename>/etc/ttys</filename> create an entry similar to the one - for <literal>ttyd0:</literal> above. Each line should get a - unique IP address from your pool of IP addresses for dynamic - users.</para> - </sect4> - - <sect4> - <title>Setting up <filename>ppp.conf</filename> for static-IP - users</title> - - <para>Along with the contents of the sample - <filename>/etc/ppp/ppp.conf</filename> above you should add a - section for each of the statically assigned dialup users. We will - continue with our <username>fred</username>, - <username>sam</username>, and <username>mary</username> - example.</para> - - <programlisting> -fred: - set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255 - -sam: - set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255 - -mary: - set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255</programlisting> - - <para>The file <filename>/etc/ppp/ppp.linkup</filename> should also - contain routing information for each static IP user if required. - The line below would add a route for the <hostid - role="ipaddr">203.14.101.0</hostid> class C via the client's - ppp link.</para> - - <programlisting> -fred: - add 203.14.101.0 netmask 255.255.255.0 HISADDR - -sam: - add 203.14.102.0 netmask 255.255.255.0 HISADDR - -mary: - add 203.14.103.0 netmask 255.255.255.0 HISADDR</programlisting> - </sect4> - - <sect4> - <title>More on <command>mgetty</command>, AutoPPP, and MS - extensions</title> - - <sect5 id="userppp-mgetty"> - <title><command>mgetty</command> and AutoPPP</title> - - <para>Configuring and compiling <command>mgetty</command> with the - <literal>AUTO_PPP</literal> option enabled allows - <command>mgetty</command> to detect the LCP phase of PPP - connections and automatically spawn off a ppp shell. However, - since the default login/password sequence does not occur it is - necessary to authenticate users using either PAP or CHAP.</para> - - <para>This section assumes the user has successfully configured, - compiled, and installed a version of <command>mgetty</command> - with the <literal>AUTO_PPP</literal> option (v0.99beta or - later)</para> - - <para>Make sure your - <filename>/usr/local/etc/mgetty+sendfax/login.config</filename> - file has the following in it:</para> - - <programlisting> -/AutoPPP/ - - /etc/ppp/ppp-pap-dialup</programlisting> - - <para>This will tell <command>mgetty</command> to run the - <filename>ppp-pap-dialup</filename> script for detected PPP - connections.</para> - - <para>Create a file called - <filename>/etc/ppp/ppp-pap-dialup</filename> containing the - following (the file should be executable):</para> - - <programlisting> -#!/bin/sh -exec /usr/sbin/ppp -direct pap$IDENT</programlisting> - - <para>For each dialup line enabled in - <filename>/etc/ttys</filename> create a corresponding entry in - <filename>/etc/ppp/ppp.conf</filename>. This will happily - co-exist with the definitions we created above.</para> - - <programlisting> -pap: - enable pap - set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40 - enable proxy</programlisting> - - <para>Each user logging in with this method will need to have a - username/password in <filename>/etc/ppp/ppp.secret</filename> - file, or alternatively add the</para> - - <programlisting> -enable passwdauth</programlisting> - - <para>option to authenticate users via pap from the - <filename>/etc/password</filename> file.</para> - - <para>If you wish to assign some users a static IP number, you can - specify the number as the third argument in - <filename>/etc/ppp/ppp.secret</filename>. See - <filename>/etc/ppp/ppp.secret.sample</filename> for - examples.</para> - </sect5> - - <sect5> - <title>MS extensions</title> - - <para>It is possible to configure PPP to supply DNS and NetBIOS - nameserver addresses on demand.</para> - - <para>To enable these extensions with PPP version 1.x, the - following lines might be added to the relevant section of - <filename>/etc/ppp/ppp.conf</filename>.</para> - - <programlisting> -enable msext -set ns 203.14.100.1 203.14.100.2 -set nbns 203.14.100.5</programlisting> - - <para>And for PPP version 2 and above:</para> - - <programlisting> -accept dns -set dns 203.14.100.1 203.14.100.2 -set nbns 203.14.100.5</programlisting> - - <para>This will tell the clients the primary and secondary name - server addresses, and a netbios nameserver host.</para> - - <para>In version 2 and above, if the <literal>set dns</literal> - line is omitted, PPP will use the values found in - <filename>/etc/resolv.conf</filename>.</para> - </sect5> - </sect4> - </sect3> - - <sect3 id="userppp-PAPnCHAP"> - <title>PAP and CHAP authentication</title> - - <para>Some ISPs set their system up so that the authentication part of - your connection is done using either of the PAP or CHAP - authentication mechanisms. If this is the case, your ISP will not - give a <prompt>login:</prompt> prompt when you connect, but will - start talking PPP immediately.</para> - - <para>PAP is less secure than CHAP, but security is not normally an - issue here as passwords, although being sent as plain text with PAP, - are being transmitted down a serial line only. There's not much room - for crackers to “eavesdrop”.</para> - - <para>Referring back to the <link linkend="userppp-staticIP">PPP and - Static IP addresses</link> or <link - linkend="userppp-dynamicIP">PPP and Dynamic IP addresses</link> - sections, the following alterations must be made:</para> - - <programlisting> -7 set login -… -12 set authname <replaceable>MyUserName</replaceable> -13 set authkey <replaceable>MyPassword</replaceable></programlisting> - - <para>As always, do not include the line numbers, they are just for - reference in this discussion. Indentation of at least one space is - required.</para> - - <variablelist> - <varlistentry> - <term>Line 7:</term> - - <listitem> - <para>Your ISP will not normally require that you log into the - server if you're using PAP or CHAP. You must therefore - disable your "set login" string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 12:</term> - - <listitem> - <para>This line specifies your PAP/CHAP user name. You will - need to insert the correct value for - <replaceable>MyUserName</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 13:</term> - - <listitem> - <para>This line specifies your PAP/CHAP password. You will need - to insert the correct value for - <replaceable>MyPassword</replaceable>. You may want to add an - additional line - - <programlisting> -15 accept PAP</programlisting> - - or - - <programlisting> -15 accept CHAP</programlisting> - - to make it obvious that this is the intention, but PAP and - CHAP are both accepted by default.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3> - <title>Changing your <command>ppp</command> configuration on the - fly</title> - - <para>It is possible to talk to the <command>ppp</command> program - while it is running in the background, but only if a suitable - diagnostic port has been set up. To do this, add the following line - to your configuration:</para> - - <programlisting> -set server /var/run/ppp-tun%d DiagnosticPassword 0177</programlisting> - - <para>This will tell PPP to listen to the specified unix-domain - socket, asking clients for the specified password before allowing - access. The <literal>%d</literal> in the name is replaced with the - <devicename>tun</devicename> device number that is in use.</para> - - <para>Once a socket has been set up, the - &man.pppctl.8; program may be used in scripts that wish to - manipulate the running program.</para> - </sect3> - </sect2> - - <sect2 id="userppp-final"> - <title>Final system configuration</title> - - <para>You now have <command>ppp</command> configured, but there are a - few more things to do before it is ready to work. They all involve - editing the <filename>/etc/rc.conf</filename> file (was - <filename>/etc/sysconfig</filename>).</para> - - <para>Working from the top down in this file, make sure the - <literal>hostname=</literal> line is set, e.g.:</para> - - <programlisting> -hostname=foo.bar.com</programlisting> - - <para>If your ISP has supplied you with a static IP address and name, - it's probably best that you use this name as your host name.</para> - - <para>Look for the <literal>network_interfaces</literal> variable. If - you want to configure your system to dial your ISP on demand, make - sure the <devicename>tun0</devicename> device is added to the list, - otherwise remove it.</para> - - <programlisting> -network_interfaces="lo0 tun0" ifconfig_tun0=</programlisting> - - <note> - <para>The <literal>ifconfig_tun0</literal> variable should be empty, - and a file called <filename>/etc/start_if.tun0</filename> should be - created. This file should contain the line</para> - - <programlisting> -ppp -auto mysystem</programlisting> - - <para>This script is executed at network configuration time, starting - your ppp daemon in automatic mode. If you have a LAN for which this - machine is a gateway, you may also wish to use the - <option>-alias</option> switch. Refer to the manual page for - further details.</para> - </note> - - <para>Set the router program to <literal>NO</literal> with the - line</para> - - <programlisting> -router_enable=NO (/etc/rc.conf) -router=NO (/etc/sysconfig)</programlisting> - - <para>It is important that the <command>routed</command> daemon is not - started (it's started by default) as <command>routed</command> tends - to delete the default routing table entries created by - <command>ppp</command>.</para> - - <para>It is probably worth your while ensuring that the - <literal>sendmail_flags</literal> line does not include the - <option>-q</option> option, otherwise <command>sendmail</command> will - attempt to do a network lookup every now and then, possibly causing - your machine to dial out. You may try:</para> - - <programlisting> -sendmail_flags="-bd"</programlisting> - - <para>The upshot of this is that you must force - <command>sendmail</command> to re-examine the mail queue whenever the - ppp link is up by typing:</para> - - <screen>&prompt.root; <userinput>/usr/sbin/sendmail -q</userinput></screen> - - <para>You may wish to use the <command>!bg</command> command in - <filename>ppp.linkup</filename> to do this automatically:</para> - - <programlisting> -1 provider: -2 delete ALL -3 add 0 0 HISADDR -4 !bg sendmail -bd -q30m</programlisting> - - <para>If you don't like this, it is possible to set up a - “dfilter” to block SMTP traffic. Refer to the sample - files for further details.</para> - - <para>All that is left is to reboot the machine.</para> - - <para>After rebooting, you can now either type</para> - - <screen>&prompt.root; <userinput>ppp</userinput></screen> - - <para>and then <command>dial provider</command> to start the PPP - session, or, if you want <command>ppp</command> to establish sessions - automatically when there is outbound traffic (and you haven't created - the <filename>start_if.tun0</filename> script), type</para> - - <screen>&prompt.root; <userinput>ppp -auto provider</userinput></screen> - </sect2> - - <sect2> - <title>Summary</title> - - <para>To recap, the following steps are necessary when setting up ppp - for the first time:</para> - - <para>Client side:</para> - - <procedure> - <step> - <para>Ensure that the <devicename>tun</devicename> device is built - into your kernel.</para> - </step> - - <step> - <para>Ensure that the - <filename>tun<replaceable>X</replaceable></filename> device file - is available in the <filename>/dev</filename> directory.</para> - </step> - - <step> - <para>Create an entry in <filename>/etc/ppp/ppp.conf</filename>. - The <filename>pmdemand</filename> example should suffice for most - ISPs.</para> - </step> - - <step> - <para>If you have a dynamic IP address, create an entry in - <filename>/etc/ppp/ppp.linkup</filename>.</para> - </step> - - <step> - <para>Update your <filename>/etc/rc.conf</filename> (or - <filename>sysconfig</filename>) file.</para> - </step> - - <step> - <para>Create a <filename>start_if.tun0</filename> script if you - require demand dialing.</para> - </step> - </procedure> - - <para>Server side:</para> - - <procedure> - <step> - <para>Ensure that the <devicename>tun</devicename> device is built - into your kernel.</para> - </step> - - <step> - <para>Ensure that the - <filename>tun<replaceable>X</replaceable></filename> device file - is available in the <filename>/dev</filename> directory.</para> - </step> - - <step> - <para>Create an entry in <filename>/etc/passwd</filename> (using the - &man.vipw.8; program).</para> - </step> - - <step> - <para>Create a profile in this users home directory that runs - <command>ppp -direct direct-server</command> or similar.</para> - </step> - - <step> - <para>Create an entry in <filename>/etc/ppp/ppp.conf</filename>. - The <filename>direct-server</filename> example should - suffice.</para> - </step> - - <step> - <para>Create an entry in - <filename>/etc/ppp/ppp.linkup</filename>.</para> - </step> - - <step> - <para>Update your <filename>/etc/rc.conf</filename> (or - <filename>sysconfig</filename>) file.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Acknowledgments</title> - - <para>This section of the handbook was last updated on Monday Aug 10, - 1998 by &a.brian;</para> - - <para>Thanks to the following for their input, comments & - suggestions:</para> - - <para>&a.nik;</para> - - <para>&a.dirkvangulik;</para> - - <para>&a.pjc;</para> - </sect2> - </sect1> - - <sect1 id="ppp"> - <title>Setting up Kernel PPP</title> - - <para><emphasis>Contributed by &a.gena;.</emphasis></para> - - <para>Before you start setting up PPP on your machine make sure that - <command>pppd</command> is located in <filename>/usr/sbin</filename> and - directory <filename>/etc/ppp</filename> exists.</para> - - <para><command>pppd</command> can work in two modes:</para> - - <orderedlist> - <listitem> - <para>as a “client”, i.e. you want to connect your machine - to outside world via PPP serial connection or modem line.</para> - </listitem> - - <listitem> - <para>as a “server”, i.e. your machine is located on the - network and used to connect other computers using PPP.</para> - </listitem> - </orderedlist> - - <para>In both cases you will need to set up an options file - (<filename>/etc/ppp/options</filename> or <filename>~/.ppprc</filename> - if you have more then one user on your machine that uses PPP).</para> - - <para>You also will need some modem/serial software (preferably kermit) so - you can dial and establish connection with remote host.</para> - - <sect2> - <title>Working as a PPP client</title> - - <para>I used the following <filename>/etc/ppp/options</filename> to - connect to CISCO terminal server PPP line.</para> - - <programlisting> -crtscts # enable hardware flow control -modem # modem control line -noipdefault # remote PPP server must supply your IP address. - # if the remote host doesn't send your IP during IPCP - # negotiation , remove this option -passive # wait for LCP packets -domain ppp.foo.com # put your domain name here - -:<remote_ip> # put the IP of remote PPP host here - # it will be used to route packets via PPP link - # if you didn't specified the noipdefault option - # change this line to <local_ip>:<remote_ip> - -defaultroute # put this if you want that PPP server will be your - # default router</programlisting> - - <para>To connect:</para> - - <procedure> - <step> - <para>Dial to the remote host using kermit (or other modem program) - enter your user name and password (or whatever is needed to enable - PPP on the remote host)</para> - </step> - - <step> - <para>Exit kermit (without hanging up the line).</para> - </step> - - <step> - <para>enter:</para> - - <screen>&prompt.root; <userinput>/usr/src/usr.sbin/pppd.new/pppd <replaceable>/dev/tty01</replaceable> <replaceable>19200</replaceable></userinput></screen> - - <para>Use the appropriate speed and device name.</para> - </step> - </procedure> - - <para>Now your computer is connected with PPP. If the connection fails - for some reasons you can add the <option>debug</option> option to the - <filename>/etc/ppp/options</filename> file and check messages on the - console to track the problem</para> - - <para>Following <filename>/etc/ppp/pppup</filename> script will make all - 3 stages automatically:</para> - - <programlisting> -#!/bin/sh -ps ax |grep pppd |grep -v grep -pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing pppd, PID=' ${pid} - kill ${pid} -fi -ps ax |grep kermit |grep -v grep -pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing kermit, PID=' ${pid} - kill -9 ${pid} -fi - -ifconfig ppp0 down -ifconfig ppp0 delete - -kermit -y /etc/ppp/kermit.dial -pppd /dev/tty01 19200</programlisting> - - <para><filename>/etc/ppp/kermit.dial</filename> is kermit script that - dials and makes all necessary authorization on the remote host. - (Example of such script is attached to the end of this - document)</para> - - <para>Use the following <filename>/etc/ppp/pppdown</filename> script to - disconnect the PPP line:</para> - - <programlisting> -#!/bin/sh -pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` -if [ X${pid} != "X" ] ; then - echo 'killing pppd, PID=' ${pid} - kill -TERM ${pid} -fi - -ps ax |grep kermit |grep -v grep -pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing kermit, PID=' ${pid} - kill -9 ${pid} -fi - -/sbin/ifconfig ppp0 down -/sbin/ifconfig ppp0 delete -kermit -y /etc/ppp/kermit.hup -/etc/ppp/ppptest</programlisting> - - <para>Check if PPP is still running - (<filename>/usr/etc/ppp/ppptest</filename>):</para> - - <programlisting> -#!/bin/sh -pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'` -if [ X${pid} != "X" ] ; then - echo 'pppd running: PID=' ${pid-NONE} -else - echo 'No pppd running.' -fi -set -x -netstat -n -I ppp0 -ifconfig ppp0</programlisting> - - <para>Hangs up modem line - (<filename>/etc/ppp/kermit.hup</filename>):</para> - - <programlisting> -set line /dev/tty01 ; put your modem device here -set speed 19200 -set file type binary -set file names literal -set win 8 -set rec pack 1024 -set send pack 1024 -set block 3 -set term bytesize 8 -set command bytesize 8 -set flow none - -pau 1 -out +++ -inp 5 OK -out ATH0\13 -echo \13 -exit</programlisting> - - <para>Here is an alternate method using <command>chat</command> instead - of <command>kermit</command>.</para> - - <para><emphasis>Contributed by &a.rhuff;.</emphasis></para> - - <para>The following two files are sufficient to accomplish a pppd - connection.</para> - - <para><filename>/etc/ppp/options</filename>:</para> - - <programlisting> -/dev/cuaa1 115200 - -crtscts # enable hardware flow control -modem # modem control line -connect "/usr/bin/chat -f /etc/ppp/login.chat.script" -noipdefault # remote PPP serve must supply your IP address. - # if the remote host doesn't send your IP during - # IPCP negotiation, remove this option -passive # wait for LCP packets -domain <your.domain> # put your domain name here - -: # put the IP of remote PPP host here - # it will be used to route packets via PPP link - # if you didn't specified the noipdefault option - # change this line to <local_ip>:<remote_ip> - -defaultroute # put this if you want that PPP server will be - # your default router</programlisting> - - <para><filename>/etc/ppp/login.chat.script</filename>:</para> - - <para>(This should actually go into a single line.)</para> - - <programlisting> -ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number> - CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id> - TIMEOUT 5 sword: <password></programlisting> - - <para>Once these are installed and modified correctly, all you need to - do is</para> - - <screen>&prompt.root; <userinput>pppd</userinput></screen> - - <para>This sample based primarily on information provided by: Trev - Roydhouse <Trev.Roydhouse@f401.n711.z3.fidonet.org> and used by - permission.</para> - </sect2> - - <sect2> - <title>Working as a PPP server</title> - - <para><filename>/etc/ppp/options</filename>:</para> - - <programlisting> -crtscts # Hardware flow control -netmask 255.255.255.0 # netmask ( not required ) -192.114.208.20:192.114.208.165 # ip's of local and remote hosts - # local ip must be different from one - # you assigned to the ethernet ( or other ) - # interface on your machine. - # remote IP is ip address that will be - # assigned to the remote machine -domain ppp.foo.com # your domain -passive # wait for LCP -modem # modem line</programlisting> - - <para>Following <filename>/etc/ppp/pppserv</filename> script will enable - ppp server on your machine:</para> - - <programlisting> -#!/bin/sh -ps ax |grep pppd |grep -v grep -pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing pppd, PID=' ${pid} - kill ${pid} -fi -ps ax |grep kermit |grep -v grep -pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing kermit, PID=' ${pid} - kill -9 ${pid} -fi - -# reset ppp interface -ifconfig ppp0 down -ifconfig ppp0 delete - -# enable autoanswer mode -kermit -y /etc/ppp/kermit.ans - -# run ppp -pppd /dev/tty01 19200</programlisting> - - <para>Use this <filename>/etc/ppp/pppservdown</filename> script to stop - ppp server:</para> - - <programlisting> -#!/bin/sh -ps ax |grep pppd |grep -v grep -pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing pppd, PID=' ${pid} - kill ${pid} -fi -ps ax |grep kermit |grep -v grep -pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing kermit, PID=' ${pid} - kill -9 ${pid} -fi -ifconfig ppp0 down -ifconfig ppp0 delete - -kermit -y /etc/ppp/kermit.noans</programlisting> - - <para>Following kermit script will enable/disable autoanswer mode on - your modem (<filename>/etc/ppp/kermit.ans</filename>):</para> - - <programlisting> -set line /dev/tty01 -set speed 19200 -set file type binary -set file names literal -set win 8 -set rec pack 1024 -set send pack 1024 -set block 3 -set term bytesize 8 -set command bytesize 8 -set flow none - -pau 1 -out +++ -inp 5 OK -out ATH0\13 -inp 5 OK -echo \13 -out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable - ; autoanswer mod -inp 5 OK -echo \13 -exit</programlisting> - - <para>This <filename>/etc/ppp/kermit.dial</filename> script is used for - dialing and authorizing on remote host. You will need to customize it - for your needs. Put your login and password in this script, also you - will need to change input statement depending on responses from your - modem and remote host.</para> - - <programlisting> -; -; put the com line attached to the modem here: -; -set line /dev/tty01 -; -; put the modem speed here: -; -set speed 19200 -set file type binary ; full 8 bit file xfer -set file names literal -set win 8 -set rec pack 1024 -set send pack 1024 -set block 3 -set term bytesize 8 -set command bytesize 8 -set flow none -set modem hayes -set dial hangup off -set carrier auto ; Then SET CARRIER if necessary, -set dial display on ; Then SET DIAL if necessary, -set input echo on -set input timeout proceed -set input case ignore -def \%x 0 ; login prompt counter -goto slhup - -:slcmd ; put the modem in command mode -echo Put the modem in command mode. -clear ; Clear unread characters from input buffer -pause 1 -output +++ ; hayes escape sequence -input 1 OK\13\10 ; wait for OK -if success goto slhup -output \13 -pause 1 -output at\13 -input 1 OK\13\10 -if fail goto slcmd ; if modem doesn't answer OK, try again - -:slhup ; hang up the phone -clear ; Clear unread characters from input buffer -pause 1 -echo Hanging up the phone. -output ath0\13 ; hayes command for on hook -input 2 OK\13\10 -if fail goto slcmd ; if no OK answer, put modem in command mode - -:sldial ; dial the number -pause 1 -echo Dialing. -output atdt9,550311\13\10 ; put phone number here -assign \%x 0 ; zero the time counter - -:look -clear ; Clear unread characters from input buffer -increment \%x ; Count the seconds -input 1 {CONNECT } -if success goto sllogin -reinput 1 {NO CARRIER\13\10} -if success goto sldial -reinput 1 {NO DIALTONE\13\10} -if success goto slnodial -reinput 1 {\255} -if success goto slhup -reinput 1 {\127} -if success goto slhup -if < \%x 60 goto look -else goto slhup - -:sllogin ; login -assign \%x 0 ; zero the time counter -pause 1 -echo Looking for login prompt. - -:slloop -increment \%x ; Count the seconds -clear ; Clear unread characters from input buffer -output \13 -; -; put your expected login prompt here: -; -input 1 {Username: } -if success goto sluid -reinput 1 {\255} -if success goto slhup -reinput 1 {\127} -if success goto slhup -if < \%x 10 goto slloop ; try 10 times to get a login prompt -else goto slhup ; hang up and start again if 10 failures - -:sluid -; -; put your userid here: -; -output ppp-login\13 -input 1 {Password: } -; -; put your password here: -; -output ppp-password\13 -input 1 {Entering SLIP mode.} -echo -quit - -:slnodial -echo \7No dialtone. Check the telephone line!\7 -exit 1 - -; local variables: -; mode: csh -; comment-start: "; " -; comment-start-skip: "; " -; end:</programlisting> - </sect2> - </sect1> - - <sect1 id="slipc"> - <title>Setting up a SLIP Client</title> - - <para><emphasis>Contributed by &a.asami; 8 Aug 1995.</emphasis></para> - - <para>The following is one way to set up a FreeBSD machine for SLIP on a - static host network. For dynamic hostname assignments (i.e., your - address changes each time you dial up), you probably need to do - something much fancier.</para> - - <para>First, determine which serial port your modem is connected to. I - have a symbolic link to <filename>/dev/modem</filename> from - <filename>/dev/cuaa1</filename>, and only use the modem name in my - configuration files. It can become quite cumbersome when you need to - fix a bunch of files in <filename>/etc</filename> and - <filename>.kermrc</filename>'s all over the system!</para> - - <note> - <para><filename>/dev/cuaa0</filename> is <devicename>COM1</devicename>, - <filename>cuaa1</filename> is <devicename>COM2</devicename>, - etc.</para> - </note> - - <para>Make sure you have - - <programlisting> -pseudo-device sl 1</programlisting> - - in your kernel's config file. It is included in the - <filename>GENERIC</filename> kernel, so this will not be a problem - unless you deleted it.</para> - - <sect2> - <title>Things you have to do only once</title> - - <procedure> - <step> - <para>Add your home machine, the gateway and nameservers to your - <filename>/etc/hosts</filename> file. Mine looks like - this:</para> - - <programlisting> -127.0.0.1 localhost loghost -136.152.64.181 silvia.HIP.Berkeley.EDU silvia.HIP silvia -136.152.64.1 inr-3.Berkeley.EDU inr-3 slip-gateway -128.32.136.9 ns1.Berkeley.edu ns1 -128.32.136.12 ns2.Berkeley.edu ns2</programlisting> - - <para>By the way, silvia is the name of the car that I had when I - was back in Japan (it is called 2?0SX here in U.S.).</para> - </step> - - <step> - <para>Make sure you have <option>hosts</option> before - <option>bind</option> in your <filename>/etc/host.conf</filename>. - Otherwise, funny things may happen.</para> - </step> - - <step> - <para>Edit the file <filename>/etc/rc.conf</filename>. Note that - you should edit the file <filename>/etc/sysconfig</filename> - instead if you are running FreeBSD previous to version - 2.2.2.</para> - - <orderedlist> - <listitem> - <para>Set your hostname by editing the line that says:</para> - - <programlisting> -hostname=myname.my.domain</programlisting> - - <para>You should give it your full Internet hostname.</para> - </listitem> - - <listitem> - <para>Add sl0 to the list of network interfaces by changing the - line that says:</para> - - <programlisting> -network_interfaces="lo0"</programlisting> - - <para>to:</para> - - <programlisting> -network_interfaces="lo0 sl0"</programlisting> - </listitem> - - <listitem> - <para>Set the startup flags of sl0 by adding a line:</para> - - <programlisting> -ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"</programlisting> - </listitem> - - <listitem> - <para>Designate the default router by changing the line:</para> - - <programlisting> -defaultrouter=NO</programlisting> - - <para>to:</para> - - <programlisting> -defaultrouter=slip-gateway</programlisting> - </listitem> - </orderedlist> - </step> - - <step> - <para>Make a file <filename>/etc/resolv.conf</filename> which - contains:</para> - - <programlisting> -domain HIP.Berkeley.EDU -nameserver 128.32.136.9 -nameserver 128.32.136.12</programlisting> - - <para>As you can see, these set up the nameserver hosts. Of course, - the actual domain names and addresses depend on your - environment.</para> - </step> - - <step> - <para>Set the password for root and toor (and any other accounts - that does not have a password). Use passwd, do not edit the - <filename>/etc/passwd</filename> or - <filename>/etc/master.passwd</filename> files!</para> - </step> - - <step> - <para>Reboot your machine and make sure it comes up with the correct - hostname.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Making a SLIP connection</title> - - <procedure> - <step> - <para>Dial up, type <command>slip</command> at the prompt, enter - your machine name and password. The things you need to enter - depends on your environment. I use kermit, with a script like - this:</para> - - <programlisting> -# kermit setup -set modem hayes -set line /dev/modem -set speed 115200 -set parity none -set flow rts/cts -set terminal bytesize 8 -set file type binary -# The next macro will dial up and login -define slip dial 643-9600, input 10 =>, if failure stop, - -output slip\x0d, input 10 Username:, if failure stop, - -output silvia\x0d, input 10 Password:, if failure stop, - -output ***\x0d, echo \x0aCONNECTED\x0a</programlisting> - - <para>(of course, you have to change the hostname and password to - fit yours). Then you can just type <command>slip</command> from - the kermit prompt to get connected.</para> - - <note> - <para>Leaving your password in plain text anywhere in the - filesystem is generally a BAD idea. Do it at your own risk. I - am just too lazy.</para> - </note> - </step> - - <step> - <para>Leave the kermit there (you can suspend it by - <command>z</command>) and as root, type:</para> - - <screen>&prompt.root; <userinput>slattach -h -c -s 115200 /dev/modem</userinput></screen> - - <para>If you are able to <command>ping</command> hosts on the other - side of the router, you are connected! If it does not work, you - might want to try <option>-a</option> instead of - <option>-c</option> as an argument to slattach.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>How to shutdown the connection</title> - - <para>Type - - <screen>&prompt.root; <userinput>kill -INT `cat /var/run/slattach.modem.pid`</userinput></screen> - - (as root) to kill slattach. Then go back to kermit - (<command>fg</command> if you suspended it) and exit from it - (<command>q</command>).</para> - - <para>The slattach man page says you have to use <command>ifconfig sl0 - down</command> to mark the interface down, but this does not seem to - make any difference for me. (<command>ifconfig sl0</command> reports - the same thing.)</para> - - <para>Some times, your modem might refuse to drop the carrier (mine - often does). In that case, simply start kermit and quit it again. It - usually goes out on the second try.</para> - </sect2> - - <sect2> - <title>Troubleshooting</title> - - <para>If it does not work, feel free to ask me. The things that people - tripped over so far:</para> - - <itemizedlist> - <listitem> - <para>Not using <option>-c</option> or <option>-a</option> in - slattach (I have no idea why this can be fatal, but adding this - flag solved the problem for at least one person)</para> - </listitem> - - <listitem> - <para>Using <option>s10</option> instead of <option>sl0</option> - (might be hard to see the difference on some fonts).</para> - </listitem> - - <listitem> - <para>Try <command>ifconfig sl0</command> to see your interface - status. I get:</para> - - <screen>&prompt.root; <userinput>ifconfig sl0</userinput> -sl0: flags=10<POINTOPOINT> - inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00</screen> - </listitem> - - <listitem> - <para>Also, <command>netstat -r</command> will give the routing - table, in case you get the "no route to host" messages from ping. - Mine looks like:</para> - - <screen>&prompt.root; <userinput>netstat -r</userinput> -Routing tables -Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks: - -(root node) -(root node) - -Route Tree for Protocol Family inet: -(root node) => -default inr-3.Berkeley.EDU UG 8 224515 sl0 - - -localhost.Berkel localhost.Berkeley UH 5 42127 lo0 - 0.438 -inr-3.Berkeley.E silvia.HIP.Berkele UH 1 0 sl0 - - -silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438 -(root node)</screen> - - <para>(this is after transferring a bunch of files, your numbers - should be smaller).</para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="slips"> - <title>Setting up a SLIP Server</title> - - <para><emphasis>Contributed by &a.ghelmer;. v1.0, 15 May - 1995.</emphasis></para> - - <para>This document provides suggestions for setting up SLIP Server - services on a FreeBSD system, which typically means configuring your - system to automatically startup connections upon login for remote SLIP - clients. The author has written this document based on his experience; - however, as your system and needs may be different, this document may - not answer all of your questions, and the author cannot be responsible - if you damage your system or lose data due to attempting to follow the - suggestions here.</para> - - <para>This guide was originally written for SLIP Server services on a - FreeBSD 1.x system. It has been modified to reflect changes in the - pathnames and the removal of the SLIP interface compression flags in - early versions of FreeBSD 2.X, which appear to be the only major changes - between FreeBSD versions. If you do encounter mistakes in this - document, please email the author with enough information to help - correct the problem.</para> - - <sect2 id="slips-prereqs"> - <title>Prerequisites</title> - - <para>This document is very technical in nature, so background knowledge - is required. It is assumed that you are familiar with the TCP/IP - network protocol, and in particular, network and node addressing, - network address masks, subnetting, routing, and routing protocols, - such as RIP. Configuring SLIP services on a dial-up server requires a - knowledge of these concepts, and if you are not familiar with them, - please read a copy of either Craig Hunt's <emphasis>TCP/IP Network - Administration</emphasis> published by O'Reilly & Associates, - Inc. (ISBN Number 0-937175-82-X), or Douglas Comer's books on the - TCP/IP protocol.</para> - - <para>It is further assumed that you have already setup your modem(s) - and configured the appropriate system files to allow logins through - your modems. If you have not prepared your system for this yet, - please see the tutorial for configuring dialup services; if you have a - World-Wide Web browser available, browse the list of tutorials at - <ulink url="http://www.FreeBSD.org/">http://www.FreeBSD.org/</ulink>; - otherwise, check the place where you found this document for a - document named <filename>dialup.txt</filename> or something similar. - You may also want to check the manual pages for - &man.sio.4; for information on the serial port device driver and - &man.ttys.5;, &man.gettytab.5;, &man.getty.8;, & &man.init.8; - for information relevant to configuring the system to accept logins on - modems, and perhaps &man.stty.1; for information on setting serial - port parameters (such as <literal>clocal</literal> for - directly-connected serial interfaces).</para> - </sect2> - - <sect2> - <title>Quick Overview</title> - - <para>In its typical configuration, using FreeBSD as a SLIP server works - as follows: a SLIP user dials up your FreeBSD SLIP Server system and - logs in with a special SLIP login ID that uses - <filename>/usr/sbin/sliplogin</filename> as the special user's shell. - The <command>sliplogin</command> program browses the file - <filename>/etc/sliphome/slip.hosts</filename> to find a matching line - for the special user, and if it finds a match, connects the serial - line to an available SLIP interface and then runs the shell script - <filename>/etc/sliphome/slip.login</filename> to configure the SLIP - interface.</para> - - <sect3> - <title>An Example of a SLIP Server Login</title> - - <para>For example, if a SLIP user ID were - <username>Shelmerg</username>, <username>Shelmerg</username>'s entry - in <filename>/etc/master.passwd</filename> would look something like - this (except it would be all on one line):</para> - - <programlisting> -Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin</programlisting> - - <para>When <username>Shelmerg</username> logs in, - <command>sliplogin</command> will search - <filename>/etc/sliphome/slip.hosts</filename> for a line that had a - matching user ID; for example, there may be a line in - <filename>/etc/sliphome/slip.hosts</filename> that reads:</para> - - <programlisting> -Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting> - - <para><command>sliplogin</command> will find that matching line, hook - the serial line into the next available SLIP interface, and then - execute <filename>/etc/sliphome/slip.login</filename> like - this:</para> - - <programlisting> -/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting> - - <para>If all goes well, <filename>/etc/sliphome/slip.login</filename> - will issue an <command>ifconfig</command> for the SLIP interface to - which <command>sliplogin</command> attached itself (slip interface - 0, in the above example, which was the first parameter in the list - given to <filename>slip.login</filename>) to set the local IP - address (<hostid>dc-slip</hostid>), remote IP address - (<hostid>sl-helmer</hostid>), network mask for the SLIP interface - (<hostid role="netmask">0xfffffc00</hostid>), and any additional - flags (<literal>autocomp</literal>). If something goes wrong, - <command>sliplogin</command> usually logs good informational - messages via the <literal>daemon</literal> syslog facility, which - usually goes into <filename>/var/log/messages</filename> (see the - manual pages for &man.syslogd.8; and - &man.syslog.conf.5, and perhaps check - <filename>/etc/syslog.conf</filename> to see to which files - <command>syslogd</command> is logging).</para> - - <para>OK, enough of the examples — let us dive into setting up - the system.</para> - </sect3> - </sect2> - - <sect2> - <title>Kernel Configuration</title> - - <para>FreeBSD's default kernels usually come with two SLIP interfaces - defined (<devicename>sl0</devicename> and - <devicename>sl1</devicename>); you can use <command>netstat - -i</command> to see whether these interfaces are defined in your - kernel.</para> - - <para>Sample output from <command>netstat -i</command>:</para> - - <screen>Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll -ed0 1500 <Link>0.0.c0.2c.5f.4a 291311 0 174209 0 133 -ed0 1500 138.247.224 ivory 291311 0 174209 0 133 -lo0 65535 <Link> 79 0 79 0 0 -lo0 65535 loop localhost 79 0 79 0 0 -sl0* 296 <Link> 0 0 0 0 0 -sl1* 296 <Link> 0 0 0 0 0</screen> - - <para>The <devicename>sl0</devicename> and <devicename>sl1</devicename> - interfaces shown in <command>netstat -i</command>'s output indicate - that there are two SLIP interfaces built into the kernel. (The - asterisks after the <literal>sl0</literal> and <literal>sl1</literal> - indicate that the interfaces are “down”.)</para> - - <para>However, FreeBSD's default kernels do not come configured to - forward packets (ie, your FreeBSD machine will not act as a router) - due to Internet RFC requirements for Internet hosts (see RFC's 1009 - [Requirements for Internet Gateways], 1122 [Requirements for Internet - Hosts — Communication Layers], and perhaps 1127 [A Perspective - on the Host Requirements RFCs]), so if you want your FreeBSD SLIP - Server to act as a router, you will have to edit the - <filename>/etc/rc.conf</filename> file (called - <filename>/etc/sysconfig</filename> in FreeBSD releases prior to - 2.2.2) and change the setting of the <literal>gateway</literal> - variable to <option>YES</option>. If you have an older system which - predates even the <filename>/etc/sysconfig</filename> file, then add - the following command: - - <programlisting> -sysctl -w net.inet.ip.forwarding = 1</programlisting> - - to your <filename>/etc/rc.local</filename> file.</para> - - <para>You will then need to reboot for the new settings to take - effect.</para> - - <para>You will notice that near the end of the default kernel - configuration file (<filename>/sys/i386/conf/GENERIC</filename>) is a - line that reads:</para> - - <programlisting> -pseudo-device sl 2</programlisting> - - <para>This is the line that defines the number of SLIP devices available - in the kernel; the number at the end of the line is the maximum number - of SLIP connections that may be operating simultaneously.</para> - - <para>Please refer to <link linkend="kernelconfig">Configuring the - FreeBSD Kernel</link> for help in reconfiguring your kernel.</para> - </sect2> - - <sect2> - <title>Sliplogin Configuration</title> - - <para>As mentioned earlier, there are three files in the - <filename>/etc/sliphome</filename> directory that are part of the - configuration for <filename>/usr/sbin/sliplogin</filename> (see - &man.sliplogin.8; for the actual manual page for - <command>sliplogin</command>): <filename>slip.hosts</filename>, which - defines the SLIP users & their associated IP addresses; - <filename>slip.login</filename>, which usually just configures the - SLIP interface; and (optionally) <filename>slip.logout</filename>, - which undoes <filename>slip.login</filename>'s effects when the serial - connection is terminated.</para> - - <sect3> - <title><filename>slip.hosts</filename> Configuration</title> - - <para><filename>/etc/sliphome/slip.hosts</filename> contains lines - which have at least four items, separated by whitespace:</para> - - <itemizedlist> - <listitem> - <para>SLIP user's login ID</para> - </listitem> - - <listitem> - <para>Local address (local to the SLIP server) of the SLIP - link</para> - </listitem> - - <listitem> - <para>Remote address of the SLIP link</para> - </listitem> - - <listitem> - <para>Network mask</para> - </listitem> - </itemizedlist> - - <para>The local and remote addresses may be host names (resolved to IP - addresses by <filename>/etc/hosts</filename> or by the domain name - service, depending on your specifications in - <filename>/etc/host.conf</filename>), and I believe the network mask - may be a name that can be resolved by a lookup into - <filename>/etc/networks</filename>. On a sample system, - <filename>/etc/sliphome/slip.hosts</filename> looks like - this:</para> - - <programlisting> -# -# login local-addr remote-addr mask opt1 opt2 -# (normal,compress,noicmp) -# -Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting> - - <para>At the end of the line is one or more of the options.</para> - - <itemizedlist> - <listitem> - <para><option>normal</option> — no header compression</para> - </listitem> - - <listitem> - <para><option>compress</option> — compress headers</para> - </listitem> - - <listitem> - <para><option>autocomp</option> — compress headers if the - remote end allows it</para> - </listitem> - - <listitem> - <para><option>noicmp</option> — disable ICMP packets (so any - “ping” packets will be dropped instead of using up - your bandwidth)</para> - </listitem> - </itemizedlist> - - <para>Note that <command>sliplogin</command> under early releases of - FreeBSD 2 ignored the options that FreeBSD 1.x recognized, so the - options <option>normal</option>, <option>compress</option>, - <option>autocomp</option>, and <option>noicmp</option> had no effect - until support was added in FreeBSD 2.2 (unless your - <filename>slip.login</filename> script included code to make use of - the flags).</para> - - <para>Your choice of local and remote addresses for your SLIP links - depends on whether you are going to dedicate a TCP/IP subnet or if - you are going to use “proxy ARP” on your SLIP server (it - is not “true” proxy ARP, but that is the terminology - used in this document to describe it). If you are not sure which - method to select or how to assign IP addresses, please refer to the - TCP/IP books referenced in the <link - linkend="slips-prereqs">slips-prereqs</link> section and/or - consult your IP network manager.</para> - - <para>If you are going to use a separate subnet for your SLIP clients, - you will need to allocate the subnet number out of your assigned IP - network number and assign each of your SLIP client's IP numbers out - of that subnet. Then, you will probably either need to configure a - static route to the SLIP subnet via your SLIP server on your nearest - IP router, or install <command>gated</command> on your FreeBSD SLIP - server and configure it to talk the appropriate routing protocols to - your other routers to inform them about your SLIP server's route to - the SLIP subnet.</para> - - <para>Otherwise, if you will use the “proxy ARP” method, - you will need to assign your SLIP client's IP addresses out of your - SLIP server's Ethernet subnet, and you will also need to adjust your - <filename>/etc/sliphome/slip.login</filename> and - <filename>/etc/sliphome/slip.logout</filename> scripts to use - &man.arp.8; to manage the proxy-ARP entries in the SLIP server's - ARP table.</para> - </sect3> - - <sect3> - <title><filename>slip.login</filename> Configuration</title> - - <para>The typical <filename>/etc/sliphome/slip.login</filename> file - looks like this:</para> - - <programlisting> -#!/bin/sh - -# -# @(#)slip.login 5.1 (Berkeley) 7/1/90 - -# -# generic login file for a slip line. sliplogin invokes this with -# the parameters: -# 1 2 3 4 5 6 7-n -# slipunit ttyspeed loginname local-addr remote-addr mask opt-args -# -/sbin/ifconfig sl$1 inet $4 $5 netmask $6</programlisting> - - <para>This <filename>slip.login</filename> file merely - <command>ifconfig</command>'s the appropriate SLIP interface with - the local and remote addresses and network mask of the SLIP - interface.</para> - - <para>If you have decided to use the “proxy ARP” method - (instead of using a separate subnet for your SLIP clients), your - <filename>/etc/sliphome/slip.login</filename> file will need to look - something like this:</para> - - <programlisting> -#!/bin/sh - -# -# @(#)slip.login 5.1 (Berkeley) 7/1/90 - -# -# generic login file for a slip line. sliplogin invokes this with -# the parameters: -# 1 2 3 4 5 6 7-n -# slipunit ttyspeed loginname local-addr remote-addr mask opt-args -# -/sbin/ifconfig sl$1 inet $4 $5 netmask $6 -# Answer ARP requests for the SLIP client with our Ethernet addr -/usr/sbin/arp -s $5 00:11:22:33:44:55 pub</programlisting> - - <para>The additional line in this <filename>slip.login</filename>, - <command>arp -s $5 00:11:22:33:44:55 pub</command>, creates an - ARP entry in the SLIP server's ARP table. This ARP entry causes the - SLIP server to respond with the SLIP server's Ethernet MAC address - whenever a another IP node on the Ethernet asks to speak to the SLIP - client's IP address.</para> - - <para>When using the example above, be sure to replace the Ethernet - MAC address (<hostid role="mac">00:11:22:33:44:55</hostid>) with the - MAC address of your system's Ethernet card, or your “proxy - ARP” will definitely not work! You can discover your SLIP - server's Ethernet MAC address by looking at the results of running - <command>netstat -i</command>; the second line of the output should - look something like:</para> - - <screen>ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116</screen> - - <para>This indicates that this particular system's Ethernet MAC - address is <hostid role="mac">00:02:c1:28:5f:4a</hostid> — the - periods in the Ethernet MAC address given by <command>netstat - -i</command> must be changed to colons and leading zeros should be - added to each single-digit hexadecimal number to convert the address - into the form that - &man.arp.8; desires; see the manual page on &man.arp.8; for - complete information on usage.</para> - - <note> - <para>When you create <filename>/etc/sliphome/slip.login</filename> - and <filename>/etc/sliphome/slip.logout</filename>, the - “execute” bit (ie, <command>chmod 755 - /etc/sliphome/slip.login /etc/sliphome/slip.logout</command>) - must be set, or <command>sliplogin</command> will be unable to - execute it.</para> - </note> - </sect3> - - <sect3> - <title><filename>slip.logout</filename> Configuration</title> - - <para><filename>/etc/sliphome/slip.logout</filename> is not strictly - needed (unless you are implementing “proxy ARP”), but if - you decide to create it, this is an example of a basic - <filename>slip.logout</filename> script:</para> - - <programlisting> -#!/bin/sh - -# -# slip.logout - -# -# logout file for a slip line. sliplogin invokes this with -# the parameters: -# 1 2 3 4 5 6 7-n -# slipunit ttyspeed loginname local-addr remote-addr mask opt-args -# -/sbin/ifconfig sl$1 down</programlisting> - - <para>If you are using “proxy ARP”, you will want to have - <filename>/etc/sliphome/slip.logout</filename> remove the ARP entry - for the SLIP client:</para> - - <programlisting> -#!/bin/sh - -# -# @(#)slip.logout - -# -# logout file for a slip line. sliplogin invokes this with -# the parameters: -# 1 2 3 4 5 6 7-n -# slipunit ttyspeed loginname local-addr remote-addr mask opt-args -# -/sbin/ifconfig sl$1 down -# Quit answering ARP requests for the SLIP client -/usr/sbin/arp -d $5</programlisting> - - <para>The <command>arp -d $5</command> removes the ARP entry that - the “proxy ARP” <filename>slip.login</filename> added - when the SLIP client logged in.</para> - - <para>It bears repeating: make sure - <filename>/etc/sliphome/slip.logout</filename> has the execute - bit set for after you create it (ie, <command>chmod - 755 /etc/sliphome/slip.logout</command>).</para> - </sect3> - </sect2> - - <sect2> - <title>Routing Considerations</title> - - <para>If you are not using the “proxy ARP” method for - routing packets between your SLIP clients and the rest of your network - (and perhaps the Internet), you will probably either have to add - static routes to your closest default router(s) to route your SLIP - client subnet via your SLIP server, or you will probably need to - install and configure <command>gated</command> on your FreeBSD SLIP - server so that it will tell your routers via appropriate routing - protocols about your SLIP subnet.</para> - - <sect3> - <title>Static Routes</title> - - <para>Adding static routes to your nearest default routers can be - troublesome (or impossible, if you do not have authority to do - so...). If you have a multiple-router network in your organization, - some routers, such as Cisco and Proteon, may not only need to be - configured with the static route to the SLIP subnet, but also need - to be told which static routes to tell other routers about, so some - expertise and troubleshooting/tweaking may be necessary to get - static-route-based routing to work.</para> - </sect3> - - <sect3> - <title>Running <command>gated</command></title> - - <para>An alternative to the headaches of static routes is to install - <command>gated</command> on your FreeBSD SLIP server and configure - it to use the appropriate routing protocols (RIP/OSPF/BGP/EGP) to - tell other routers about your SLIP subnet. You can use - <command>gated</command> from the <link linkend="ports">ports - collection</link> or retrieve and build it yourself from <ulink - URL="ftp://ftp.gated.merit.edu/research.and.development/gated/">the - GateD anonymous ftp site</ulink>; I believe the current version as - of this writing is <filename>gated-R3_5Alpha_8.tar.Z</filename>, - which includes support for FreeBSD “out-of-the-box”. - Complete information and documentation on <command>gated</command> - is available on the Web starting at <ulink - URL="http://www.gated.merit.edu/">the Merit GateD - Consortium</ulink>. Compile and install it, and then write a - <filename>/etc/gated.conf</filename> file to configure your gated; - here is a sample, similar to what the author used on a FreeBSD SLIP - server:</para> - - <programlisting> -# -# gated configuration file for dc.dsu.edu; for gated version 3.5alpha5 -# Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface -# -# -# tracing options -# -traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ; - -rip yes { - interface sl noripout noripin ; - interface ed ripin ripout version 1 ; - traceoptions route ; -} ; - -# -# Turn on a bunch of tracing info for the interface to the kernel: -kernel { - traceoptions remnants request routes info interface ; -} ; - -# -# Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP -# - -export proto rip interface ed { - proto direct { - <replaceable>xxx.xxx.yy</replaceable> mask 255.255.252.0 metric 1; # SLIP connections - } ; -} ; - -# -# Accept routes from RIP via ed Ethernet interfaces - -import proto rip interface ed { - all ; -} ;</programlisting> - - <para>The above sample <filename>gated.conf</filename> file broadcasts - routing information regarding the SLIP subnet - <replaceable>xxx.xxx.yy</replaceable> via RIP onto the Ethernet; if - you are using a different Ethernet driver than the - <devicename>ed</devicename> driver, you will need to change the - references to the <devicename>ed</devicename> interface - appropriately. This sample file also sets up tracing to - <filename>/var/tmp/gated.output</filename> for debugging - <command>gated</command>'s activity; you can certainly turn off the - tracing options if <command>gated</command> works OK for you. You - will need to change the <replaceable>xxx.xxx.yy</replaceable>'s into - the network address of your own SLIP subnet (be sure to change the - net mask in the <literal>proto direct</literal> clause as - well).</para> - - <para>When you get <command>gated</command> built and installed and - create a configuration file for it, you will need to run - <command>gated</command> in place of <command>routed</command> on - your FreeBSD system; change the <filename>routed/gated</filename> - startup parameters in <filename>/etc/netstart</filename> as - appropriate for your system. Please see the manual page for - <command>gated</command> for information on - <command>gated</command>'s command-line parameters.</para> - </sect3> - </sect2> - - <sect2> - <title>Acknowledgments</title> - - <para>Thanks to these people for comments and advice regarding this - tutorial:</para> - - <variablelist> - <varlistentry> - <term>&a.wilko;</term> - - <listitem> - <para></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Piero Serini</term> - - <listitem> - <para><email>Piero@Strider.Inet.IT</email></para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/printing/chapter.sgml b/en/handbook/printing/chapter.sgml deleted file mode 100644 index 615765ce16..0000000000 --- a/en/handbook/printing/chapter.sgml +++ /dev/null @@ -1,4665 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.17 1999-08-05 20:48:22 nik Exp $ ---> - -<chapter id="printing"> - <title>Printing</title> - - <para><emphasis>Contributed by &a.kelly; 30 September - 1995</emphasis></para> - - <para>In order to use printers with FreeBSD, you will need to set them up to - work with the Berkeley line printer spooling system, also known as the LPD - spooling system. It is the standard printer control system in FreeBSD. - This section introduces the LPD spooling system, often simply called - LPD.</para> - - <para>If you are already familiar with LPD or another printer spooling - system, you may wish to skip to section <link - linkend="printing-intro-setup">Setting up the spooling - system</link>.</para> - - <sect1 id="printing-intro-spooler"> - <title>What the Spooler Does</title> - - <para>LPD controls everything about a host's printers. It is responsible - for a number of things:</para> - - <itemizedlist> - <listitem> - <para>It controls access to attached printers and printers attached to - other hosts on the network.</para> - </listitem> - - <listitem> - <para>It enables users to submit files to be printed; these - submissions are known as <emphasis>jobs</emphasis>.</para> - </listitem> - - <listitem> - <para>It prevents multiple users from accessing a printer at the same - time by maintaining a <emphasis>queue</emphasis> for each - printer.</para> - </listitem> - - <listitem> - <para>It can print <emphasis>header pages</emphasis> (also known as - <emphasis>banner</emphasis> or <emphasis>burst</emphasis> pages) so - users can easily find jobs they have printed in a stack of - printouts.</para> - </listitem> - - <listitem> - <para>It takes care of communications parameters for printers - connected on serial ports.</para> - </listitem> - - <listitem> - <para>It can send jobs over the network to another LPD spooler on - another host.</para> - </listitem> - - <listitem> - <para>It can run special filters to format jobs to be printed for - various printer languages or printer capabilities.</para> - </listitem> - - <listitem> - <para>It can account for printer usage.</para> - </listitem> - </itemizedlist> - - <para>Through a configuration file, and by providing the special filter - programs, you can enable the LPD system to do all or some subset of the - above for a great variety of printer hardware.</para> - </sect1> - - <sect1 id="printing-intro-why"> - <title>Why You Should Use the Spooler</title> - - <para>If you are the sole user of your system, you may be wondering why - you should bother with the spooler when you do not need access control, - header pages, or printer accounting. While it is possible to enable - direct access to a printer, you should use the spooler anyway - since</para> - - <itemizedlist> - <listitem> - <para>LPD prints jobs in the background; you do not have to wait for - data to be copied to the printer.</para> - </listitem> - - <listitem> - <para>LPD can conveniently run a job to be printed through filters to - add date/time headers or convert a special file format (such as a - TeX DVI file) into a format the printer will understand. You will - not have to do these steps manually.</para> - </listitem> - - <listitem> - <para>Many free and commercial programs that provide a print feature - usually expect to talk to the spooler on your system. By setting up - the spooling system, you will more easily support other software you - may later add or already have.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="printing-intro-setup"> - <title>Setting Up the Spooling System</title> - - <para>To use printers with the LPD spooling system, you will need to set - up both your printer hardware and the LPD software. This document - describes two levels of setup:</para> - - <itemizedlist> - <listitem> - <para>See section <link linkend="printing-simple">Simple Printer - Setup</link> to learn how to connect a printer, tell LPD how to - communicate with it, and print plain text files to the - printer.</para> - </listitem> - - <listitem> - <para>See section <link linkend="printing-advanced">Advanced Printer - Setup</link> to find out how to print a variety of special file - formats, to print header pages, to print across a network, to - control access to printers, and to do printer accounting.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="printing-simple"> - <title>Simple Printer Setup</title> - - <para>This section tells how to configure printer hardware and the LPD - software to use the printer. It teaches the basics:</para> - - <itemizedlist> - <listitem> - <para>Section <link linkend="printing-hardware">Hardware Setup</link> - gives some hints on connecting the printer to a port on your - computer.</para> - </listitem> - - <listitem> - <para>Section <link linkend="printing-software">Software Setup</link> - shows how to setup the LPD spooler configuration file - <filename>/etc/printcap</filename>.</para> - </listitem> - </itemizedlist> - - <para>If you are setting up a printer that uses a network protocol to - accept data to print instead of a serial or parallel interface, see - <link linkend="printing-advanced-network-net-if">Printers With Networked - Data Stream Interaces</link>.</para> - - <para>Although this section is called “Simple Printer Setup,” - it is actually fairly complex. Getting the printer to work with your - computer and the LPD spooler is the hardest part. The advanced options - like header pages and accounting are fairly easy once you get the - printer working.</para> - - <sect2 id="printing-hardware"> - <title>Hardware Setup</title> - - <para>This section tells about the various ways you can connect a - printer to your PC. It talks about the kinds of ports and cables, and - also the kernel configuration you may need to enable FreeBSD to speak - to the printer.</para> - - <para>If you have already connected your printer and have successfully - printed with it under another operating system, you can probably skip - to section <link linkend="printing-software">Software - Setup</link>.</para> - - <sect3 id="printing-ports"> - <title>Ports and Cables</title> - - <para>Nearly all printers you can get for a PC today support one or - both of the following interfaces:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Serial</emphasis> interfaces use a serial port on - your computer to send data to the printer. Serial interfaces - are common in the computer industry and cables are readily - available and also easy to construct. Serial interfaces - sometimes need special cables and might require you to configure - somewhat complex communications options.</para> - </listitem> - - <listitem> - <para><emphasis>Parallel</emphasis> interfaces use a parallel port - on your computer to send data to the printer. Parallel - interfaces are common in the PC market. Cables are readily - available but more difficult to construct by hand. There are - usually no communications options with parallel interfaces, - making their configuration exceedingly simple.</para> - - <para>Parallel interfaces are sometimes known as - “Centronics” interfaces, named after the connector - type on the printer.</para> - </listitem> - </itemizedlist> - - <para>In general, serial interfaces are slower than parallel - interfaces. Parallel interfaces usually offer just one-way - communication (computer to printer) while serial gives you two-way. - Many newer parallel ports can also receive data from the printer, - but only few printers need to send data back to the computer. And - FreeBSD does not support two-way parallel communication yet.</para> - - <para>Usually, the only time you need two-way communication with the - printer is if the printer speaks PostScript. PostScript printers - can be very verbose. In fact, PostScript jobs are actually programs - sent to the printer; they need not produce paper at all and may - return results directly to the computer. PostScript also uses - two-way communication to tell the computer about problems, such as - errors in the PostScript program or paper jams. Your users may be - appreciative of such information. Furthermore, the best way to do - effective accounting with a PostScript printer requires two-way - communication: you ask the printer for its page count (how many - pages it has printed in its lifetime), then send the user's job, - then ask again for its page count. Subtract the two values and you - know how much paper to charge the user.</para> - - <para>So, which interface should you use?</para> - - <itemizedlist> - <listitem> - <para>If you need two-way communication, use a serial port. - FreeBSD does not yet support two-way communication over a - parallel port.</para> - </listitem> - - <listitem> - <para>If you do not need two-way communication and can pick - parallel or serial, prefer the parallel interface. It keeps a - serial port free for other peripherals—such as a terminal - or a modem—and is faster most of the time. It is also - easier to configure.</para> - </listitem> - - <listitem> - <para>Finally, use whatever works.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3 id="printing-parallel"> - <title>Parallel Ports</title> - - <para>To hook up a printer using a parallel interface, connect the - Centronics cable between the printer and the computer. The - instructions that came with the printer, the computer, or both - should give you complete guidance.</para> - - <para>Remember which parallel port you used on the computer. The - first parallel port is <filename>/dev/lpt0</filename> to FreeBSD; - the second is <filename>/dev/lpt1</filename>, and so on.</para> - </sect3> - - <sect3 id="printing-serial"> - <title>Serial Ports</title> - - <para>To hook up a printer using a serial interface, connect the - proper serial cable between the printer and the computer. The - instructions that came with the printer, the computer, or both - should give you complete guidance.</para> - - <para>If you are unsure what the “proper serial cable” is, - you may wish to try one of the following alternatives:</para> - - <itemizedlist> - <listitem> - <para>A <emphasis>modem</emphasis> cable connects each pin of the - connector on one end of the cable straight through to its - corresponding pin of the connector on the other end. This type - of cable is also known as a “DTE-to-DCE” - cable.</para> - </listitem> - - <listitem> - <para>A <emphasis>null-modem</emphasis> cable connects some pins - straight through, swaps others (send data to receive data, for - example), and shorts some internally in each connector hood. - This type of cable is also known as a “DTE-to-DTE” - cable.</para> - </listitem> - - <listitem> - <para>A <emphasis>serial printer</emphasis> cable, required for - some unusual printers, is like the null modem cable, but sends - some signals to their counterparts instead of being internally - shorted.</para> - </listitem> - </itemizedlist> - - <para>You should also set up the communications parameters for the - printer, usually through front-panel controls or DIP switches on the - printer. Choose the highest bps (bits per second, sometimes - <emphasis>baud rate</emphasis>) rate that both your computer and the - printer can support. Choose 7 or 8 data bits; none, even, or odd - parity; and 1 or 2 stop bits. Also choose a flow control protocol: - either none, or XON/XOFF (also known as “in-band” or - “software”) flow control. Remember these settings for - the software configuration that follows.</para> - </sect3> - </sect2> - - <sect2 id="printing-software"> - <title>Software Setup</title> - - <para>This section describes the software setup necessary to print - with the LPD spooling system in FreeBSD.</para> - - <para>Here is an outline of the steps involved:</para> - - <procedure> - <step> - <para>Configure your kernel, if necessary, for the port you are - using for the printer; section <link - linkend="printing-kernel">Kernel Configuration</link> tells you - what you need to do.</para> - </step> - - <step> - <para>Set the communications mode for the parallel port, if you are - using a parallel port; section <link - linkend="printing-parallel-port-mode">Setting the Communication - Mode for the Parallel Port</link> gives details.</para> - </step> - - <step> - <para>Test if the operating system can send data to the printer. - Section <link linkend="printing-testing">Checking Printer - Communications</link> gives some suggestions on how to do - this.</para> - </step> - - <step> - <para>Set up LPD for the printer by modifying the file - <filename>/etc/printcap</filename>. Section <link - linkend="printing-printcap">The /etc/printcap File</link> shows - you how.</para> - </step> - </procedure> - - <sect3 id="printing-kernel"> - <title>Kernel Configuration</title> - - <para>The operating system kernel is compiled to work with a specific - set of devices. The serial or parallel interface for your printer - is a part of that set. Therefore, it might be necessary to add - support for an additional serial or parallel port if your kernel is - not already configured for one.</para> - - <para>To find out if the kernel you are currently using supports a - serial interface, type:</para> - - <screen>&prompt.root; <userinput>dmesg | grep sio<replaceable>N</replaceable></userinput></screen> - - <para>Where <replaceable>N</replaceable> is the number of the serial - port, starting from zero. If you see output similar to the - following:</para> - - <screen>sio2 at 0x3e8-0x3ef irq 5 on isa -sio2: type 16550A</screen> - - <para>then the kernel supports the port.</para> - - <para>To find out if the kernel supports a parallel interface, - type:</para> - - <screen>&prompt.root; <userinput>dmesg | grep lpt<replaceable>N</replaceable></userinput></screen> - - <para>Where <replaceable>N</replaceable> is the number of the parallel - port, starting from zero. If you see output similar to the - following <screen>lpt0 at 0x378-0x37f on isa</screen> then the - kernel supports the port.</para> - - <para>You might have to reconfigure your kernel in order for the - operating system to recognize and use the parallel or serial port - you are using for the printer.</para> - - <para>To add support for a serial port, see the section on kernel - configuration. To add support for a parallel port, see that section - <emphasis>and</emphasis> the section that follows.</para> - - <sect4 id="printing-dev-ports"> - <title>Adding <filename>/dev</filename> Entries for the Ports</title> - - <para>Even though the kernel may support communication along a - serial or parallel port, you will still need a software interface - through which programs running on the system can send and receive - data. That is what entries in the <filename>/dev</filename> - directory are for.</para> - - <para><emphasis>To add a <filename>/dev</filename> entry for a - port:</emphasis></para> - - <procedure> - <step> - <para>Become root with the &man.su.1; command. Enter the root - password when prompted.</para> - </step> - - <step> - <para>Change to the <filename>/dev</filename> directory:</para> - - <screen>&prompt.root; cd /dev</screen> - - </step> - - <step> - <para>Type:</para> - - <screen>&prompt.root; <userinput>./MAKEDEV <replaceable>port</replaceable></userinput></screen> - - <para>Where <replaceable>port</replaceable> is the device entry - for the port you want to make. Use <literal>lpt0</literal> - for the first parallel port, <literal>lpt1</literal> for the - second, and so on; use <literal>ttyd0</literal> for the first - serial port, <literal>ttyd1</literal> for the second, and so - on.</para> - </step> - - <step> - <para>Type:</para> - - <screen>&prompt.root; <userinput>ls -l <replaceable>port</replaceable></userinput></screen> - - <para>to make sure the device entry got created.</para> - </step> - </procedure> - </sect4> - - <sect4 id="printing-parallel-port-mode"> - <title>Setting the Communication Mode for the Parallel Port</title> - - <para>When you are using the parallel interface, you can choose - whether FreeBSD should use interrupt-driven or polled - communication with the printer.</para> - - <itemizedlist> - <listitem> - <para>The <emphasis>interrupt-driven</emphasis> method is the - default with the GENERIC kernel. With this method, the - operating system uses an IRQ line to determine when the - printer is ready for data.</para> - </listitem> - - <listitem> - <para>The <emphasis>polled</emphasis> method directs the - operating system to repeatedly ask the printer if it is ready - for more data. When it responds ready, the kernel sends more - data.</para> - </listitem> - </itemizedlist> - - <para>The interrupt-driven method is somewhat faster but uses up a - precious IRQ line. You should use whichever one works.</para> - - <para>You can set the communications mode in two ways: by - configuring the kernel or by using the &man.lptcontrol.8; - program.</para> - - <para><emphasis>To set the communications mode by configuring the - kernel:</emphasis></para> - - <procedure> - <step> - <para>Edit your kernel configuration file. Look for or add an - <literal>lpt0</literal> entry. If you are setting up the - second parallel port, use <literal>lpt1</literal> instead. - Use <literal>lpt2</literal> for the third port, and so - on.</para> - - <itemizedlist> - <listitem> - <para>If you want interrupt-driven mode, add the - <literal>irq</literal> specifier:</para> - - <programlisting> -device lpt0 at isa? port? tty irq <replaceable>N</replaceable> vector lptintr</programlisting> - - <para>Where <replaceable>N</replaceable> is the IRQ number - for your computer's parallel port.</para> - </listitem> - - <listitem> - <para>If you want polled mode, do not add the - <literal>irq</literal> specifier:</para> - - <programlisting> -device lpt0 at isa? port? tty vector lptintr</programlisting> - </listitem> - </itemizedlist> - </step> - - <step> - <para>Save the file. Then configure, build, and install the - kernel, then reboot. See <link linkend="kernelconfig">kernel - configuration</link> for more details.</para> - </step> - </procedure> - - <para><emphasis>To set the communications mode with</emphasis> - &man.lptcontrol.8;:</para> - - <procedure> - <step> - <para>Type:</para> - - <screen>&prompt.root; <userinput>lptcontrol -i -u <replaceable>N</replaceable></userinput></screen> - - <para>to set interrupt-driven mode for - <literal>lpt<replaceable>N</replaceable></literal>.</para> - </step> - - <step> - <para>Type:</para> - - <screen>&prompt.root; <userinput>lptcontrol -p -u <replaceable>N</replaceable></userinput></screen> - - <para>to set polled-mode for - <literal>lpt<replaceable>N</replaceable></literal>.</para> - </step> - </procedure> - - <para>You could put these commands in your - <filename>/etc/rc.local</filename> file to set the mode each time - your system boots. See &man.lptcontrol.8; for more - information.</para> - </sect4> - - <sect4 id="printing-testing"> - <title>Checking Printer Communications</title> - - <para>Before proceeding to configure the spooling system, you should - make sure the operating system can successfully send data to your - printer. It is a lot easier to debug printer communication and - the spooling system separately.</para> - - <para>To test the printer, we will send some text to it. For - printers that can immediately print characters sent to them, - the program &man.lptest.1; is perfect: it generates all 96 - printable ASCII characters in 96 lines.</para> - - <para>For a PostScript (or other language-based) printer, we will - need a more sophisticated test. A small PostScript program, such - as the following, will suffice:</para> - - <programlisting> -%!PS -100 100 moveto 300 300 lineto stroke -310 310 moveto /Helvetica findfont 12 scalefont setfont -(Is this thing working?) show -showpage</programlisting> - - <note> - <para>When this document refers to a printer language, I am - assuming a language like PostScript, and not Hewlett Packard's - PCL. Although PCL has great functionality, you can intermingle - plain text with its escape sequences. PostScript cannot directly - print plain text, and that is the kind of printer language for - which we must make special accommodations.</para> - </note> - - <sect5 id="printing-checking-parallel"> - <title>Checking a Parallel Printer</title> - - <para>This section tells you how to check if FreeBSD can - communicate with a printer connected to a parallel port.</para> - - <para><emphasis>To test a printer on a parallel - port:</emphasis></para> - - <procedure> - <step> - <para>Become root with &man.su.1;.</para> - </step> - - <step> - <para>Send data to the printer.</para> - - <itemizedlist> - <listitem> - <para>If the printer can print plain text, then use - &man.lptest.1;. Type:</para> - - <screen>&prompt.root; <userinput>lptest > /dev/lpt<replaceable>N</replaceable></userinput></screen> - - <para>Where <replaceable>N</replaceable> is the number of - the parallel port, starting from zero.</para> - </listitem> - - <listitem> - <para>If the printer understands PostScript or other - printer language, then send a small program to the - printer. Type:</para> - - <screen>&prompt.root; <userinput>cat > /dev/lpt<replaceable>N</replaceable></userinput></screen> - - <para>Then, line by line, type the program - <emphasis>carefully</emphasis> as you cannot edit a line - once you have pressed RETURN or ENTER. When you have - finished entering the program, press CONTROL+D, or - whatever your end of file key is.</para> - - <para>Alternatively, you can put the program in a file and - type:</para> - - <screen>&prompt.root; <userinput>cat <replaceable>file</replaceable> > /dev/lpt<replaceable>N</replaceable></userinput></screen> - - <para>Where <replaceable>file</replaceable> is the name of - the file containing the program you want to send to the - printer.</para> - </listitem> - </itemizedlist> - </step> - </procedure> - - <para>You should see something print. Do not worry if the text - does not look right; we will fix such things later.</para> - </sect5> - - <sect5 id="printing-checking-serial"> - <title>Checking a Serial Printer</title> - - <para>This section tells you how to check if FreeBSD can - communicate with a printer on a serial port.</para> - - <para><emphasis>To test a printer on a serial - port:</emphasis></para> - - <procedure> - <step> - <para>Become root with &man.su.1;.</para> - </step> - - <step> - <para>Edit the file <filename>/etc/remote</filename>. Add the - following entry:</para> - - <programlisting> -printer:dv=/dev/<replaceable>port</replaceable>:br#<replaceable>bps-rate</replaceable>:pa=<replaceable>parity</replaceable></programlisting> - - <para>Where <replaceable>port</replaceable> is the device - entry for the serial port (<literal>ttyd0</literal>, - <literal>ttyd1</literal>, etc.), - <replaceable>bps-rate</replaceable> is the bits-per-second - rate at which the printer communicates, and - <replaceable>parity</replaceable> is the parity required by - the printer (either <literal>even</literal>, - <literal>odd</literal>, <literal>none</literal>, or - <literal>zero</literal>).</para> - - <para>Here is a sample entry for a printer connected via a - serial line to the third serial port at 19200 bps with no - parity:</para> - - <programlisting> -printer:dv=/dev/ttyd2:br#19200:pa=none</programlisting> - </step> - - <step> - <para>Connect to the printer with &man.tip.1;. Type:</para> - - <screen>&prompt.root; <userinput>tip printer</userinput></screen> - - <para>If this step does not work, edit the file - <filename>/etc/remote</filename> again and try using - <filename>/dev/cuaa<replaceable>N</replaceable></filename> - instead of - <filename>/dev/ttyd<replaceable>N</replaceable></filename>.</para> - </step> - - <step> - <para>Send data to the printer.</para> - - <itemizedlist> - <listitem> - <para>If the printer can print plain text, then use - &man.lptest.1;. Type:</para> - - <screen><prompt>~</prompt><userinput>$lptest</userinput></screen> - </listitem> - - <listitem> - <para>If the printer understands PostScript or other - printer language, then send a small program to the - printer. Type the program, line by line, <emphasis>very - carefully</emphasis> as backspacing or other editing - keys may be significant to the printer. You may also - need to type a special end-of-file key for the printer - so it knows it received the whole program. For - PostScript printers, press CONTROL+D.</para> - - <para>Alternatively, you can put the program in a file and - type:</para> - - <screen><prompt>~</prompt><userinput>><replaceable>file</replaceable></userinput></screen> - - <para>Where <replaceable>file</replaceable> is the name of - the file containing the program. After - &man.tip.1; sends the file, press any required - end-of-file key.</para> - </listitem> - </itemizedlist> - </step> - </procedure> - - <para>You should see something print. Do not worry if the text - does not look right; we will fix that later.</para> - </sect5> - </sect4> - </sect3> - - <sect3 id="printing-printcap"> - <title>Enabling the Spooler: The <filename>/etc/printcap</filename> - File</title> - - <para>At this point, your printer should be hooked up, your kernel - configured to communicate with it (if necessary), and you have been - able to send some simple data to the printer. Now, we are ready to - configure LPD to control access to your printer.</para> - - <para>You configure LPD by editing the file - <filename>/etc/printcap</filename>. The LPD spooling system reads - this file each time the spooler is used, so updates to the file take - immediate effect.</para> - - <para>The format of the &man.printcap.5; file is straightforward. Use - your favorite text editor to make changes to - <filename>/etc/printcap</filename>. The format is identical to - other capability files like - <filename>/usr/share/misc/termcap</filename> and - <filename>/etc/remote</filename>. For complete information about - the format, see the &man.cgetent.3;.</para> - - <para>The simple spooler configuration consists of the following - steps:</para> - - <procedure> - <step> - <para>Pick a name (and a few convenient aliases) for the printer, - and put them in the <filename>/etc/printcap</filename> file; see - <link linkend="printing-naming">Naming the - Printer</link>.</para> - </step> - - <step> - <para>Turn off header pages (which are on by default) by inserting - the <literal>sh</literal> capability; see <link - linkend="printing-no-header-pages">Suppressing Header - Pages</link>.</para> - </step> - - <step> - <para>Make a spooling directory, and specify its location with the - <literal>sd</literal> capability; see <link - linkend="printing-spooldir">Making the Spooling - Directory</link>.</para> - </step> - - <step> - <para>Set the <filename>/dev</filename> entry to use for the - printer, and note it in <filename>/etc/printcap</filename> with - the <literal>lp</literal> capability; see <link - linkend="printing-device">Identifying the Printer - Device</link>. Also, if the printer is on a serial port, set - up the communication parameters with the <literal>fs</literal>, - <literal>fc</literal>, <literal>xs</literal>, and - <literal>xc</literal> capabilities; see <link - linkend="printing-commparam">Configuring Spooler - Communications Parameters</link>.</para> - </step> - - <step> - <para>Install a plain text input filter; see <link - linkend="printing-textfilter">Installing the Text - Filter</link></para> - </step> - - <step> - <para>Test the setup by printing something with the - &man.lpr.1; command; see <link - linkend="printing-trying">Trying It Out</link> and <link - linkend="printing-troubleshooting">Troubleshooting</link>.</para> - </step> - </procedure> - - <note> - <para>Language-based printers, such as PostScript printers, cannot - directly print plain text. The simple setup outlined above and - described in the following sections assumes that if you are - installing such a printer you will print only files that the - printer can understand.</para> - </note> - - <para>Users often expect that they can print plain text to any of the - printers installed on your system. Programs that interface to LPD - to do their printing usually make the same assumption. If you are - installing such a printer and want to be able to print jobs in the - printer language <emphasis>and</emphasis> print plain text jobs, you - are strongly urged to add an additional step to the simple setup - outlined above: install an automatic plain-text-to-PostScript (or - other printer language) conversion program. Section <link - linkend="printing-advanced-if-conversion">Accommodating Plain Text - Jobs on PostScript Printers</link> tells how to do this.</para> - - <sect4 id="printing-naming"> - <title>Naming the Printer</title> - - <para>The first (easy) step is to pick a name for your printer. It - really does not matter whether you choose functional or whimsical - names since you can also provide a number aliases for the - printer.</para> - - <para>At least one of the printers specified in the - <filename>/etc/printcap</filename> should have the alias - <literal>lp</literal>. This is the default printer's name. If - users do not have the <envar>PRINTER</envar> environment variable - nor specify a printer name on the command line of any of the LPD - commands, then <literal>lp</literal> will be the default printer - they get to use.</para> - - <para>Also, it is common practice to make the last alias for a - printer be a full description of the printer, including make and - model.</para> - - <para>Once you have picked a name and some common aliases, put them - in the <filename>/etc/printcap</filename> file. The name of the - printer should start in the leftmost column. Separate each alias - with a vertical bar and put a colon after the last alias.</para> - - <para>In the following example, we start with a skeletal - <filename>/etc/printcap</filename> that defines two printers (a - Diablo 630 line printer and a Panasonic KX-P4455 PostScript laser - printer):</para> - - <programlisting> -# -# /etc/printcap for host rose -# -rattan|line|diablo|lp|Diablo 630 Line Printer: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:</programlisting> - - <para>In this example, the first printer is named - <literal>rattan</literal> and has as aliases - <literal>line</literal>, <literal>diablo</literal>, - <literal>lp</literal>, and <literal>Diablo 630 Line - Printer</literal>. Since it has the alias - <literal>lp</literal>, it is also the default printer. The second - is named <literal>bamboo</literal>, and has as aliases - <literal>ps</literal>, <literal>PS</literal>, - <literal>S</literal>, <literal>panasonic</literal>, and - <literal>Panasonic KX-P4455 PostScript v51.4</literal>.</para> - </sect4> - - <sect4 id="printing-no-header-pages"> - <title>Suppressing Header Pages</title> - - <para>The LPD spooling system will by default print a - <emphasis>header page</emphasis> for each job. The header page - contains the user name who requested the job, the host from which - the job came, and the name of the job, in nice large letters. - Unfortunately, all this extra text gets in the way of debugging - the simple printer setup, so we will suppress header pages.</para> - - <para>To suppress header pages, add the <literal>sh</literal> - capability to the entry for the printer in - <filename>/etc/printcap</filename>. Here is the example - <filename>/etc/printcap</filename> with <literal>sh</literal> - added:</para> - - <programlisting> -# -# /etc/printcap for host rose - no header pages anywhere -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:</programlisting> - - <para>Note how we used the correct format: the first line starts in - the leftmost column, and subsequent lines are indented with a - single TAB. Every line in an entry except the last ends in a - backslash character.</para> - </sect4> - - <sect4 id="printing-spooldir"> - <title>Making the Spooling Directory</title> - - <para>The next step in the simple spooler setup is to make a - <emphasis>spooling directory</emphasis>, a directory where print - jobs reside until they are printed, and where a number of other - spooler support files live.</para> - - <para>Because of the variable nature of spooling directories, it is - customary to put these directories under - <filename>/var/spool</filename>. It is not necessary to backup - the contents of spooling directories, either. Recreating them is - as simple as running &man.mkdir.1;.</para> - - <para>It is also customary to make the directory with a name that is - identical to the name of the printer, as shown below:</para> - - <screen>&prompt.root; <userinput>mkdir /var/spool/<replaceable>printer-name</replaceable></userinput></screen> - - <para>However, if you have a lot of printers on your network, you - might want to put the spooling directories under a single - directory that you reserve just for printing with LPD. We will do - this for our two example printers <literal>rattan</literal> and - <literal>bamboo</literal>:</para> - - <screen>&prompt.root; <userinput>mkdir /var/spool/lpd</userinput> -&prompt.root; <userinput>mkdir /var/spool/lpd/rattan</userinput> -&prompt.root; <userinput>mkdir /var/spool/lpd/bamboo</userinput></screen> - - <note> - <para>If you are concerned about the privacy of jobs that users - print, you might want to protect the spooling directory so it is - not publicly accessible. Spooling directories should be owned - and be readable, writable, and searchable by user daemon and - group daemon, and no one else. We will do this for our example - printers:</para> - - <screen>&prompt.root; <userinput>chown daemon.daemon /var/spool/lpd/rattan</userinput> -&prompt.root; <userinput>chown daemon.daemon /var/spool/lpd/bamboo</userinput> -&prompt.root; <userinput>chmod 770 /var/spool/lpd/rattan</userinput> -&prompt.root; <userinput>chmod 770 /var/spool/lpd/bamboo</userinput></screen> - </note> - - <para>Finally, you need to tell LPD about these directories using - the <filename>/etc/printcap</filename> file. You specify the - pathname of the spooling directory with the <literal>sd</literal> - capability:</para> - - <programlisting> -# -# /etc/printcap for host rose - added spooling directories -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:</programlisting> - - <para>Note that the name of the printer starts in the first column - but all other entries describing the printer should be indented - with a tab and each line escaped with a backslash.</para> - - <para>If you do not specify a spooling directory with - <literal>sd</literal>, the spooling system will use - <filename>/var/spool/lpd</filename> as a default.</para> - </sect4> - - <sect4 id="printing-device"> - <title>Identifying the Printer Device</title> - - <para>In section <link linkend="printing-dev-ports">Adding /dev - Entries for the Ports</link>, we identified which entry in the - <filename>/dev</filename> directory FreeBSD will use to - communicate with the printer. Now, we tell LPD that information. - When the spooling system has a job to print, it will open the - specified device on behalf of the filter program (which is - responsible for passing data to the printer).</para> - - <para>List the <filename>/dev</filename> entry pathname in the - <filename>/etc/printcap</filename> file using the - <literal>lp</literal> capability.</para> - - <para>In our running example, let us assume that - <hostid>rattan</hostid> is on the first parallel port, and - <hostid>bamboo</hostid> is on a sixth serial port; here are the - additions to <filename>/etc/printcap</filename>:</para> - - <programlisting> -# -# /etc/printcap for host rose - identified what devices to use -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:</programlisting> - - <para>If you do not specify the <literal>lp</literal> capability for - a printer in your <filename>/etc/printcap</filename> file, LPD - uses <filename>/dev/lp</filename> as a default. - <filename>/dev/lp</filename> currently does not exist in - FreeBSD.</para> - - <para>If the printer you are installing is connected to a parallel - port, skip to the section <link - linkend="printing-textfilter">Installing the Text Filter</link>. - Otherwise, be sure to follow the instructions in the next - section.</para> - </sect4> - - <sect4 id="printing-commparam"> - <title>Configuring Spooler Communication Parameters</title> - - <para>For printers on serial ports, LPD can set up the bps rate, - parity, and other serial communication parameters on behalf of the - filter program that sends data to the printer. This is - advantageous since:</para> - - <itemizedlist> - <listitem> - <para>It lets you try different communication parameters by - simply editing the <filename>/etc/printcap</filename> file; - you do not have to recompile the filter program.</para> - </listitem> - - <listitem> - <para>It enables the spooling system to use the same filter - program for multiple printers which may have different serial - communication settings.</para> - </listitem> - </itemizedlist> - - <para>The following <filename>/etc/printcap</filename> capabilities - control serial communication parameters of the device listed in - the <literal>lp</literal> capability:</para> - - <variablelist> - <varlistentry> - <term><literal>br#<replaceable>bps-rate</replaceable></literal></term> - - <listitem> - <para>Sets the communications speed of the device to - <replaceable>bps-rate</replaceable>, where - <replaceable>bps-rate</replaceable> can be 50, 75, 110, 134, - 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, or - 38400 bits-per-second.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>fc#<replaceable>clear-bits</replaceable></literal></term> - - <listitem> - <para>Clears the flag bits - <replaceable>clear-bits</replaceable> in the - <replaceable>sgttyb</replaceable> structure after opening - the device.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>fs#<replaceable>set-bits</replaceable></literal></term> - - <listitem> - <para>Sets the flag bits <replaceable>set-bits</replaceable> - in the <replaceable>sgttyb</replaceable> structure.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>xc#<replaceable>clear-bits</replaceable></literal></term> - - <listitem> - <para>Clears local mode bits - <replaceable>clear-bits</replaceable> after opening the - device.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>xs#<replaceable>set-bits</replaceable></literal></term> - - <listitem> - <para>Sets local mode bits - <replaceable>set-bits</replaceable>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information on the bits for the - <literal>fc</literal>, <literal>fs</literal>, - <literal>xc</literal>, and <literal>xs</literal> capabilities, see - the file - <filename>/usr/include/sys/ioctl_compat.h</filename>.</para> - - <para>When LPD opens the device specified by the - <literal>lp</literal> capability, it reads the flag bits in the - <literal>sgttyb</literal> structure; it clears any bits in the - <literal>fc</literal> capability, then sets bits in the - <literal>fs</literal> capability, then applies the resultant - setting. It does the same for the local mode bits as well.</para> - - <para>Let us add to our example printer on the sixth serial port. - We will set the bps rate to 38400. For the flag bits, we will set - the TANDEM, ANYP, LITOUT, FLUSHO, and PASS8 flags. For the local - mode bits, we will set the LITOUT and PASS8 flags:</para> - - <programlisting> -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:fs#0x82000c1:xs#0x820:</programlisting> - </sect4> - - <sect4 id="printing-textfilter"> - <title>Installing the Text Filter</title> - - <para>We are now ready to tell LPD what text filter to use to send - jobs to the printer. A <emphasis>text filter</emphasis>, also - known as an <emphasis>input filter</emphasis>, is a program that - LPD runs when it has a job to print. When LPD runs the text - filter for a printer, it sets the filter's standard input to the - job to print, and its standard output to the printer device - specified with the <literal>lp</literal> capability. The filter - is expected to read the job from standard input, perform any - necessary translation for the printer, and write the results to - standard output, which will get printed. For more information on - the text filter, see section <link - linkend="printing-advanced-filters">Filters</link>.</para> - - <para>For our simple printer setup, the text filter can be a small - shell script that just executes <command>/bin/cat</command> to - send the job to the printer. FreeBSD comes with another filter - called <filename>lpf</filename> that handles backspacing and - underlining for printers that might not deal with such character - streams well. And, of course, you can use any other filter - program you want. The filter <command>lpf</command> is described - in detail in section <link linkend="printing-advanced-lpf">lpf: a - Text Filter</link>.</para> - - <para>First, let us make the shell script - <filename>/usr/local/libexec/if-simple</filename> be a simple text - filter. Put the following text into that file with your favorite - text editor:</para> - - <programlisting> -#!/bin/sh -# -# if-simple - Simple text input filter for lpd -# Installed in /usr/local/libexec/if-simple -# -# Simply copies stdin to stdout. Ignores all filter arguments. - -/bin/cat && exit 0 -exit 2</programlisting> - - <para>Make the file executable:</para> - - <screen>&prompt.root; <userinput>chmod 555 /usr/local/libexec/if-simple</userinput></screen> - - <para>And then tell LPD to use it by specifying it with the - <literal>if</literal> capability in - <filename>/etc/printcap</filename>. We will add it to the two - printers we have so far in the example - <filename>/etc/printcap</filename>:</para> - - <programlisting> -# -# /etc/printcap for host rose - added text filter -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:\ - :if=/usr/local/libexec/if-simple:</programlisting> - </sect4> - - <sect4 id="printing-trying"> - <title>Trying It Out</title> - - <para>You have reached the end of the simple LPD setup. - Unfortunately, congratulations are not quite yet in order, since - we still have to test the setup and correct any problems. To test - the setup, try printing something. To print with the LPD system, - you use the command &man.lpr.1;, - which submits a job for printing.</para> - - <para>You can combine &man.lpr.1; with the &man.lptest.1; program, - introduced in section <link linkend="printing-testing">Checking - Printer Communications</link> to generate some test text.</para> - - <para><emphasis>To test the simple LPD setup:</emphasis></para> - - <para>Type:</para> - - <screen>&prompt.root; <userinput>lptest 20 5 | lpr -P<replaceable>printer-name</replaceable></userinput></screen> - - <para>Where <replaceable>printer-name</replaceable> is a the name of - a printer (or an alias) specified in - <filename>/etc/printcap</filename>. To test the default printer, - type &man.lpr.1; without any - <option>-P</option> argument. Again, if you are testing a printer - that expects PostScript, send a PostScript program in that - language instead of using &man.lptest.1;. You can do so by - putting the program in a file and typing <command>lpr - <replaceable>file</replaceable></command>.</para> - - <para>For a PostScript printer, you should get the results of the - program. If you are using &man.lptest.1;, then your results - should look like the following:</para> - - <programlisting> -!"#$%&'()*+,-./01234 -"#$%&'()*+,-./012345 -#$%&'()*+,-./0123456 -$%&'()*+,-./01234567 -%&'()*+,-./012345678</programlisting> - - <para>To further test the printer, try downloading larger programs - (for language-based printers) or running &man.lptest.1; with - different arguments. For example, <command>lptest 80 60 - </command> will produce 60 lines of 80 characters each.</para> - - <para>If the printer did not work, see the next section, <link - linkend="printing-troubleshooting">Troubleshooting</link>.</para> - </sect4> - - <sect4 id="printing-troubleshooting"> - <title>Troubleshooting</title> - - <para>After performing the simple test with &man.lptest.1;, you - might have gotten one of the following results instead of the - correct printout:</para> - - <variablelist> - <varlistentry> - <term>It worked, after awhile; or, it did not eject a full - sheet.</term> - - <listitem> - <para>The printer printed the above, but it sat for awhile and - did nothing. In fact, you might have needed to press a - PRINT REMAINING or FORM FEED button on the printer to get - any results to appear.</para> - - <para>If this is the case, the printer was probably waiting to - see if there was any more data for your job before it - printed anything. To fix this problem, you can have the - text filter send a FORM FEED character (or whatever is - necessary) to the printer. This is usually sufficient to - have the printer immediately print any text remaining in its - internal buffer. It is also useful to make sure each print - job ends on a full sheet, so the next job does not start - somewhere on the middle of the last page of the previous - job.</para> - - <para>The following replacement for the shell script - <filename>/usr/local/libexec/if-simple</filename> prints a - form feed after it sends the job to the printer:</para> - - <programlisting> -#!/bin/sh -# -# if-simple - Simple text input filter for lpd -# Installed in /usr/local/libexec/if-simple -# -# Simply copies stdin to stdout. Ignores all filter arguments. -# Writes a form feed character (\f) after printing job. - -/bin/cat && printf "\f" && exit 0 -exit 2</programlisting> - </listitem> - </varlistentry> - - <varlistentry> - <term>It produced the “staircase effect.”</term> - - <listitem> - <para>You got the following on paper:</para> - - <programlisting> -!"#$%&'()*+,-./01234 - "#$%&'()*+,-./012345 - #$%&'()*+,-./0123456</programlisting> - - <para>You have become another victim of the - <emphasis>staircase effect</emphasis>, caused by conflicting - interpretations of what characters should indicate a - new-line. UNIX-style operating systems use a single - character: ASCII code 10, the line feed (LF). MS-DOS, OS/2, - and others uses a pair of characters, ASCII code 10 - <emphasis>and</emphasis> ASCII code 13 (the carriage return - or CR). Many printers use the MS-DOS convention for - representing new-lines.</para> - - <para>When you print with FreeBSD, your text used just the - line feed character. The printer, upon seeing a line feed - character, advanced the paper one line, but maintained the - same horizontal position on the page for the next character - to print. That is what the carriage return is for: to move - the location of the next character to print to the left edge - of the paper.</para> - - <para>Here is what FreeBSD wants your printer to do:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry>Printer received CR</entry> - <entry>Printer prints CR</entry> - </row> - - <row> - <entry>Printer received LF</entry> - <entry>Printer prints CR + LF</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Here are some ways to achieve this:</para> - - <itemizedlist> - <listitem> - <para>Use the printer's configuration switches or control - panel to alter its interpretation of these characters. - Check your printer's manual to find out how to do - this.</para> - - <note> - <para>If you boot your system into other operating - systems besides FreeBSD, you may have to - <emphasis>reconfigure</emphasis> the printer to use a - an interpretation for CR and LF characters that those - other operating systems use. You might prefer one of - the other solutions, below.</para> - </note> - </listitem> - - <listitem> - <para>Have FreeBSD's serial line driver automatically - convert LF to CR+LF. Of course, this works with - printers on serial ports <emphasis>only</emphasis>. To - enable this feature, set the CRMOD bit in - <literal>fs</literal> capability in the - <filename>/etc/printcap</filename> file for the - printer.</para> - </listitem> - - <listitem> - <para>Send an <emphasis>escape code</emphasis> to the - printer to have it temporarily treat LF characters - differently. Consult your printer's manual for escape - codes that your printer might support. When you find - the proper escape code, modify the text filter to send - the code first, then send the print job.</para> - - <para>Here is an example text filter for printers that - understand the Hewlett-Packard PCL escape codes. This - filter makes the printer treat LF characters as a LF and - CR; then it sends the job; then it sends a form feed to - eject the last page of the job. It should work with - nearly all Hewlett Packard printers.</para> - - <programlisting> -#!/bin/sh -# -# hpif - Simple text input filter for lpd for HP-PCL based printers -# Installed in /usr/local/libexec/hpif -# -# Simply copies stdin to stdout. Ignores all filter arguments. -# Tells printer to treat LF as CR+LF. Ejects the page when done. - -printf "\033&k2G" && cat && printf "\033&l0H" && exit 0 -exit 2</programlisting> - - <para>Here is an example - <filename>/etc/printcap</filename> from a host called - orchid. It has a single printer attached to its first - parallel port, a Hewlett Packard LaserJet 3Si named - <hostid>teak</hostid>. It is using the above script as - its text filter:</para> - - <programlisting> -# -# /etc/printcap for host orchid -# -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\ - :if=/usr/local/libexec/hpif:</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>It overprinted each line.</term> - - <listitem> - <para>The printer never advanced a line. All of the lines of - text were printed on top of each other on one line.</para> - - <para>This problem is the “opposite” of the - staircase effect, described above, and is much rarer. - Somewhere, the LF characters that FreeBSD uses to end a line - are being treated as CR characters to return the print - location to the left edge of the paper, but not also down a - line.</para> - - <para>Use the printer's configuration switches or control - panel to enforce the following interpretation of LF and CR - characters:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Printer receives</entry> - <entry>Printer prints</entry> - </row> - </thead> - - <tbody> - <row> - <entry>CR</entry> - <entry>CR</entry> - </row> - - <row> - <entry>LF</entry> - <entry>CR + LF</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </listitem> - </varlistentry> - - <varlistentry><term>The printer lost characters.</term> - - <listitem> - <para>While printing, the printer did not print a few - characters in each line. The problem might have gotten - worse as the printer ran, losing more and more - characters.</para> - - <para>The problem is that the printer cannot keep up with the - speed at which the computer sends data over a serial line. - (This problem should not occur with printers on parallel - ports.) There are two ways to overcome the problem:</para> - - <itemizedlist> - <listitem> - <para>If the printer supports XON/XOFF flow control, have - FreeBSD use it by specifying the TANDEM bit in the - <literal>fs</literal> capability.</para> - </listitem> - - <listitem> - <para>If the printer supports carrier flow control, - specify the MDMBUF bit in the <literal>fs</literal> - capability. Make sure the cable connecting the printer - to the computer is correctly wired for carrier flow - control.</para> - </listitem> - - <listitem> - <para>If the printer does not support any flow control, - use some combination of the NLDELAY, TBDELAY, CRDELAY, - VTDELAY, and BSDELAY bits in the <literal>fs</literal> - capability to add appropriate delays to the stream of - data sent to the printer.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>It printed garbage.</term> - - <listitem> - <para>The printer printed what appeared to be random garbage, - but not the desired text.</para> - - <para>This is usually another symptom of incorrect - communications parameters with a serial printer. - Double-check the bps rate in the <literal>br</literal> - capability, and the parity bits in the <literal>fs</literal> - and <literal>fc</literal> capabilities; make sure the - printer is using the same settings as specified in the - <filename>/etc/printcap</filename> file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Nothing happened.</term> - - <listitem> - <para>If nothing happened, the problem is probably within - FreeBSD and not the hardware. Add the log file - (<literal>lf</literal>) capability to the entry for the - printer you are debugging in the - <filename>/etc/printcap</filename> file. For example, here - is the entry for <literal>rattan</literal>, with the - <literal>lf</literal> capability:</para> - - <programlisting> -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple:\ - :lf=/var/log/rattan.log</programlisting> - - <para>Then, try printing again. Check the log file (in our - example, <filename>/var/log/rattan.log</filename>) to see - any error messages that might appear. Based on the messages - you see, try to correct the problem.</para> - - <para>If you do not specify a <literal>lf</literal> - capability, LPD uses <filename>/dev/console</filename> as a - default.</para> - </listitem> - </varlistentry> - </variablelist> - </sect4> - </sect3> - </sect2> - </sect1> - - <sect1 id="printing-using"> - <title>Using Printers</title> - - <para>This section tells you how to use printers you have setup with - FreeBSD. Here is an overview of the user-level commands:</para> - - <variablelist> - <varlistentry> - <term>&man.lpr.1;</term> - - <listitem> - <para>Print jobs</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&man.lpq.1;</term> - - <listitem> - <para>Check printer queues</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&man.lprm.1;</term> - - <listitem> - <para>Remove jobs from a printer's queue</para> - </listitem> - </varlistentry> - </variablelist> - - <para>There is also an administrative command, &man.lpc.8;, described in - the section <link linkend="printing-lpc">Administrating the LPD - Spooler</link>, used to control printers and their queues.</para> - - <para>All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1; - accept an option <option>-P - <replaceable>printer-name</replaceable></option> to specify on which - printer/queue to operate, as listed in the - <filename>/etc/printcap</filename> file. This enables you to submit, - remove, and check on jobs for various printers. If you do not use the - <option>-P</option> option, then these commands use the printer - specified in the <envar>PRINTER</envar> environment variable. Finally, - if you do not have a <envar>PRINTER</envar> environment variable, these - commands default to the printer named <literal>lp</literal>.</para> - - <para>Hereafter, the terminology <emphasis>default printer</emphasis> - means the printer named in the <envar>PRINTER</envar> environment - variable, or the printer named <literal>lp</literal> when there is no - <envar>PRINTER</envar> environment variable.</para> - - <sect2 id="printing-lpr"> - <title>Printing Jobs</title> - - <para>To print files, type:</para> - - <screen>&prompt.user; <userinput>lpr <replaceable>filename</replaceable> <replaceable>...</replaceable></userinput></screen> - - <para>This prints each of the listed files to the default printer. If - you list no files, &man.lpr.1; reads data to - print from standard input. For example, this command prints some - important system files:</para> - - <screen>&prompt.user; <userinput>lpr /etc/host.conf /etc/hosts.equiv</userinput></screen> - - <para>To select a specific printer, type:</para> - - <screen>&prompt.user; <userinput>lpr -P <replaceable>printer-name</replaceable> <replaceable>filename</replaceable> <replaceable>...</replaceable></userinput></screen> - - <para>This example prints a long listing of the current directory to the - printer named <literal>rattan</literal>:</para> - - <screen>&prompt.user; <userinput>ls -l | lpr -P rattan</userinput></screen> - - <para>Because no files were listed for the - &man.lpr.1; command, <command>lpr</command> read the data to print - from standard input, which was the output of the <command>ls - -l</command> command.</para> - - <para>The &man.lpr.1; command can also accept a wide variety of options - to control formatting, apply file conversions, generate multiple - copies, and so forth. For more information, see the section <link - linkend="printing-lpr-options">Printing Options</link>.</para> - </sect2> - - <sect2 id="printing-lpq"> - <title>Checking Jobs</title> - - <para>When you print with &man.lpr.1;, the data you wish to print is put - together in a package called a “print job”, which is sent - to the LPD spooling system. Each printer has a queue of jobs, and - your job waits in that queue along with other jobs from yourself and - from other users. The printer prints those jobs in a first-come, - first-served order.</para> - - <para>To display the queue for the default printer, type &man.lpq.1;. - For a specific printer, use the <option>-P</option> option. For - example, the command - - <screen>&prompt.user; <userinput>lpq -P bamboo</userinput></screen> - - shows the queue for the printer named <hostid>bamboo</hostid>. Here - is an example of the output of the <command>lpq</command> - command:</para> - - <screen>bamboo is ready and printing -Rank Owner Job Files Total Size -active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes -2nd kelly 10 (standard input) 1635 bytes -3rd mary 11 ... 78519 bytes</screen> - - <para>This shows three jobs in the queue for <literal>bamboo</literal>. - The first job, submitted by user kelly, got assigned “job - number” 9. Every job for a printer gets a unique job number. - Most of the time you can ignore the job number, but you will need it - if you want to cancel the job; see section <link - linkend="printing-lprm">Removing Jobs</link> for details.</para> - - <para>Job number nine consists of two files; multiple files given on the - &man.lpr.1; command line are treated as part of a single job. It - is the currently active job (note the word <literal>active</literal> - under the “Rank” column), which means the printer should - be currently printing that job. The second job consists of data - passed as the standard input to the &man.lpr.1; command. The third - job came from user <username>mary</username>; it is a much larger - job. The pathname of the files she's trying to print is too long to - fit, so the &man.lpq.1; command just shows three dots.</para> - - <para>The very first line of the output from &man.lpq.1; is also useful: - it tells what the printer is currently doing (or at least what LPD - thinks the printer is doing).</para> - - <para>The &man.lpq.1; command also support a <option>-l</option> option - to generate a detailed long listing. Here is an example of - <command>lpq -l</command>:</para> - - <screen>waiting for bamboo to become ready (offline ?) -kelly: 1st [job 009rose] - /etc/host.conf 73 bytes - /etc/hosts.equiv 15 bytes - -kelly: 2nd [job 010rose] - (standard input) 1635 bytes - -mary: 3rd [job 011rose] - /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes</screen> - </sect2> - - <sect2 id="printing-lprm"> - <title>Removing Jobs</title> - - <para>If you change your mind about printing a job, you can remove the - job from the queue with the &man.lprm.1; command. Often, you can - even use &man.lprm.1; to remove an active job, but some or all of the - job might still get printed.</para> - - <para>To remove a job from the default printer, first use - &man.lpq.1; to find the job number. Then type:</para> - - <screen>&prompt.user; <userinput>lprm <replaceable>job-number</replaceable></userinput></screen> - - <para>To remove the job from a specific printer, add the - <option>-P</option> option. The following command removes job number - 10 from the queue for the printer <hostid>bamboo</hostid>:</para> - - <screen>&prompt.user; <userinput>lprm -P bamboo 10</userinput></screen> - - <para>The &man.lprm.1; command has a few shortcuts:</para> - - <variablelist> - <varlistentry> - <term>lprm -</term> - - <listitem> - <para>Removes all jobs (for the default printer) belonging to - you.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>lprm <replaceable>user</replaceable></term> - - <listitem> - <para>Removes all jobs (for the default printer) belonging to - <replaceable>user</replaceable>. The superuser can remove other - users' jobs; you can remove only your own jobs.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>lprm</term> - - <listitem> - <para>With no job number, user name, or <option>-</option> - appearing on the command line, - &man.lprm.1; removes the currently active job on the - default printer, if it belongs to you. The superuser can remove - any active job.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Just use the <option>-P</option> option with the above shortcuts - to operate on a specific printer instead of the default. For example, - the following command removes all jobs for the current user in the - queue for the printer named <literal>rattan</literal>:</para> - - <screen>&prompt.user; <userinput>lprm -P rattan -</userinput></screen> - - <note> - <para>If you are working in a networked environment, &man.lprm.1; will - let you remove jobs only from the - host from which the jobs were submitted, even if the same printer is - available from other hosts. The following command sequence - demonstrates this:</para> - - <screen>&prompt.user; <userinput>lpr -P rattan myfile</userinput> -&prompt.user; <userinput>rlogin orchid</userinput> -&prompt.user; <userinput>lpq -P rattan</userinput> -Rank Owner Job Files Total Size -active seeyan 12 ... 49123 bytes -2nd kelly 13 myfile 12 bytes -&prompt.user; <userinput>lprm -P rattan 13</userinput> -rose: Permission denied -&prompt.user; <userinput>logout</userinput> -&prompt.user; <userinput>lprm -P rattan 13</userinput> -dfA013rose dequeued -cfA013rose dequeued - </screen> - </note> - </sect2> - - <sect2 id="printing-lpr-options"> - <title>Beyond Plain Text: Printing Options</title> - - <para>The &man.lpr.1; command supports a number of options that control - formatting text, converting graphic and other file formats, producing - multiple copies, handling of the job, and more. This section - describes the options.</para> - - <sect3 id="printing-lpr-options-format"> - <title>Formatting and Conversion Options</title> - - <para>The following &man.lpr.1; options control formatting of the - files in the job. Use these options if the job does not contain - plain text or if you want plain text formatted through the - &man.pr.1; utility.</para> - - <para>For example, the following command prints a DVI file (from the - TeX typesetting system) named <filename>fish-report.dvi</filename> - to the printer named <literal>bamboo</literal>:</para> - - <screen>&prompt.user; <userinput>lpr -P bamboo -d fish-report.dvi</userinput></screen> - - <para>These options apply to every file in the job, so you cannot mix - (say) DVI and ditroff files together in a job. Instead, submit the - files as separate jobs, using a different conversion option for each - job.</para> - - <note> - <para>All of these options except <option>-p</option> and - <option>-T</option> require conversion filters installed for the - destination printer. For example, the <option>-d</option> option - requires the DVI conversion filter. Section <link - linkend="printing-advanced-convfilters">Conversion - Filters</link> gives details.</para> - </note> - - <variablelist> - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>Print cifplot files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-d</option></term> - - <listitem> - <para>Print DVI files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-f</option></term> - - <listitem> - <para>Print FORTRAN text files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - - <listitem> - <para>Print plot data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-i <replaceable>number</replaceable></option></term> - - <listitem> - <para>Indent the output by <replaceable>number</replaceable> - columns; if you omit <replaceable>number</replaceable>, indent - by 8 columns. This option works only with certain conversion - filters.</para> - - <note> - <para>Do not put any space between the <option>-i</option> and - the number.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - - <listitem> - <para>Print literal text data, including control - characters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - - <listitem> - <para>Print ditroff (device independent troff) data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-p</term> - - <listitem> - <para>Format plain text with &man.pr.1; before printing. See - &man.pr.1; for more information.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-T <replaceable>title</replaceable></option></term> - - <listitem> - <para>Use <replaceable>title</replaceable> on the - &man.pr.1; header instead of the file name. This option has - effect only when used with the <option>-p</option> - option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-t</option></term> - - <listitem> - <para>Print troff data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v</option></term> - - <listitem> - <para>Print raster data.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Here is an example: this command prints a nicely formatted - version of the &man.ls.1; manual page on the default printer:</para> - - <screen>&prompt.user; <userinput>zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t</userinput></screen> - - <para>The &man.zcat.1; command uncompresses the source of the</para> - - <para>&man.ls.1; manual page and passes it to the &man.troff.1; - command, which formats that source and makes GNU troff output and - passes it to &man.lpr.1;, which submits the job to the LPD spooler. - Because we used the <option>-t</option> option to</para> - - <para>&man.lpr.1;, the spooler will convert the GNU troff output into - a format the default printer can understand when it prints the - job.</para> - </sect3> - - <sect3 id="printing-lpr-options-job-handling"> - <title>Job Handling Options</title> - - <para>The following options to &man.lpr.1; tell LPD to handle the job - specially:</para> - - <variablelist> - <varlistentry> - <term>-# <replaceable>copies</replaceable></term> - - <listitem> - <para>Produce a number of <replaceable>copies</replaceable> of - each file in the job instead of just one copy. An - administrator may disable this option to reduce printer - wear-and-tear and encourage photocopier usage. See section - <link - linkend="printing-advanced-restricting-copies">Restricting - Multiple Copies</link>.</para> - - <para>This example prints three copies of - <filename>parser.c</filename> followed by three copies of - <filename>parser.h</filename> to the default printer:</para> - - <screen>&prompt.user; <userinput>lpr -#3 parser.c parser.h</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term>-m</term> - - <listitem> - <para>Send mail after completing the print job. With this - option, the LPD system will send mail to your account when it - finishes handling your job. In its message, it will tell you - if the job completed successfully or if there was an error, - and (often) what the error was.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-s</term> - - <listitem> - <para>Do not copy the files to the spooling directory, but make - symbolic links to them instead.</para> - - <para>If you are printing a large job, you probably want to use - this option. It saves space in the spooling directory (your - job might overflow the free space on the filesystem where the - spooling directory resides). It saves time as well since LPD - will not have to copy each and every byte of your job to the - spooling directory.</para> - - <para>There is a drawback, though: since LPD will refer to the - original files directly, you cannot modify or remove them - until they have been printed.</para> - - <note> - <para>If you are printing to a remote printer, LPD will - eventually have to copy files from the local host to the - remote host, so the <option>-s</option> option will save - space only on the local spooling directory, not the remote. - It is still useful, though.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>-r</term> - - <listitem> - <para>Remove the files in the job after copying them to the - spooling directory, or after printing them with the - <option>-s</option> option. Be careful with this - option!</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3 id="printing-lpr-options-misc"> - <title>Header Page Options</title> - - <para>These options to &man.lpr.1; adjust the text that normally - appears on a job's header page. If header pages are suppressed for - the destination printer, these options have no effect. See section - <link linkend="printing-advanced-header-pages">Header Pages</link> - for information about setting up header pages.</para> - - <variablelist> - <varlistentry> - <term>-C <replaceable>text</replaceable></term> - - <listitem> - <para>Replace the hostname on the header page with - <replaceable>text</replaceable>. The hostname is normally the - name of the host from which the job was submitted.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-J <replaceable>text</replaceable></term> - - <listitem> - <para>Replace the job name on the header page with - <replaceable>text</replaceable>. The job name is normally the - name of the first file of the job, or - <filename>stdin</filename> if you are printing standard - input.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-h</term> - - <listitem> - <para>Do not print any header page.</para> - - <note> - <para>At some sites, this option may have no effect due to the - way header pages are generated. See <link - linkend="printing-advanced-header-pages">Header - Pages</link> for details.</para> - </note> - </listitem> - </varlistentry> - </variablelist> - </sect3> - </sect2> - - <sect2 id="printing-lpc"> - <title>Administrating Printers</title> - - <para>As an administrator for your printers, you have had to install, - set up, and test them. Using the &man.lpc.8; command, you - can interact with your printers in yet more ways. With &man.lpc.8;, - you can</para> - - <itemizedlist> - <listitem> - <para>Start and stop the printers</para> - </listitem> - - <listitem> - <para>Enable and disable their queues</para> - </listitem> - - <listitem> - <para>Rearrange the order of the jobs in each queue.</para> - </listitem> - </itemizedlist> - - <para>First, a note about terminology: if a printer is - <emphasis>stopped</emphasis>, it will not print anything in its queue. - Users can still submit jobs, which will wait in the queue until the - printer is <emphasis>started</emphasis> or the queue is - cleared.</para> - - <para>If a queue is <emphasis>disabled</emphasis>, no user (except root) - can submit jobs for the printer. An <emphasis>enabled</emphasis> - queue allows jobs to be submitted. A printer can be - <emphasis>started</emphasis> for a disabled queue, in which case it - will continue to print jobs in the queue until the queue is - empty.</para> - - <para>In general, you have to have root privileges to use the - &man.lpc.8; command. Ordinary users can use the &man.lpc.8; command - to get printer status and to restart a hung printer only.</para> - - <para>Here is a summary of the &man.lpc.8; commands. Most of the - commands takes a <replaceable>printer-name</replaceable> argument to - tell on which printer to operate. You can use <literal>all</literal> - for the <replaceable>printer-name</replaceable> to mean all printers - listed in <filename>/etc/printcap</filename>.</para> - - <variablelist> - <varlistentry> - <term><command>abort - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Cancel the current job and stop the printer. Users can - still submit jobs if the queue's enabled.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>clean - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Remove old files from the printer's spooling directory. - Occasionally, the files that make up a job are not properly - removed by LPD, particularly if there have been errors during - printing or a lot of administrative activity. This command - finds files that do not belong in the spooling directory and - removes them.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>disable - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Disable queuing of new jobs. If the printer's started, it - will continue to print any jobs remaining in the queue. The - superuser (root) can always submit jobs, even to a disabled - queue.</para> - - <para>This command is useful while you are testing a new printer - or filter installation: disable the queue and submit jobs as - root. Other users will not be able to submit jobs until you - complete your testing and re-enable the queue with the - <command>enable</command> command.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>down <replaceable>printer-name</replaceable> - <replaceable>message</replaceable></command></term> - - <listitem> - <para>Take a printer down. Equivalent to - <command>disable</command> followed by <command>stop</command>. - The <replaceable>message</replaceable> appears as the printer's - status whenever a user checks the printer's queue with - &man.lpq.1; or status with <command>lpc - status</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>enable - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Enable the queue for a printer. Users can submit jobs but - the printer will not print anything until it is started.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>help - <replaceable>command-name</replaceable></command></term> - - <listitem> - <para>Print help on the command - <replaceable>command-name</replaceable>. With no - <replaceable>command-name</replaceable>, print a summary of the - commands available.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>restart - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Start the printer. Ordinary users can use this command if - some extraordinary circumstance hangs LPD, but they cannot start - a printer stopped with either the <command>stop</command> or - <command>down</command> commands. The - <command>restart</command> command is equivalent to - <command>abort</command> followed by - <command>start</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>start - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Start the printer. The printer will print jobs in its - queue.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>stop - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Stop the printer. The printer will finish the current job - and will not print anything else in its queue. Even though the - printer is stopped, users can still submit jobs to an enabled - queue.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>topq <replaceable>printer-name</replaceable> - <replaceable>job-or-username</replaceable></command></term> - - <listitem> - <para>Rearrange the queue for - <replaceable>printer-name</replaceable> by placing the jobs with - the listed <replaceable>job</replaceable> numbers or the jobs - belonging to <replaceable>username</replaceable> at the top of - the queue. For this command, you cannot use - <literal>all</literal> as the - <replaceable>printer-name</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>up - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Bring a printer up; the opposite of the - <command>down</command> command. Equivalent to - <command>start</command> followed by - <command>enable</command>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>&man.lpc.8; accepts the above commands on the command line. If - you do not enter any commands, &man.lpc.8; enters an interactive mode, - where you can enter commands until you type <command>exit</command>, - <command>quit</command>, or end-of-file.</para> - </sect2> - </sect1> - - <sect1 id="printing-advanced"> - <title>Advanced Printer Setup</title> - - <para>This section describes filters for printing specially formatted - files, header pages, printing across networks, and restricting and - accounting for printer usage.</para> - - <sect2 id="printing-advanced-filter-intro"> - <title>Filters</title> - - <para>Although LPD handles network protocols, queuing, access control, - and other aspects of printing, most of the <emphasis>real</emphasis> - work happens in the <emphasis>filters</emphasis>. Filters are - programs that communicate with the printer and handle its device - dependencies and special requirements. In the simple printer setup, - we installed a plain text filter—an extremely simple one that - should work with most printers (section <link - linkend="printing-textfilter">Installing the Text - Filter</link>).</para> - - <para>However, in order to take advantage of format conversion, printer - accounting, specific printer quirks, and so on, you should understand - how filters work. It will ultimately be the filter's responsibility - to handle these aspects. And the bad news is that most of the time - <emphasis>you</emphasis> have to provide filters yourself. The good - news is that many are generally available; when they are not, they are - usually easy to write.</para> - - <para>Also, FreeBSD comes with one, - <filename>/usr/libexec/lpr/lpf</filename>, that works with many - printers that can print plain text. (It handles backspacing and tabs - in the file, and does accounting, but that is about all it does.) - There are also several filters and filter components in the FreeBSD - ports collection.</para> - - <para>Here is what you will find in this section:</para> - - <itemizedlist> - <listitem> - <para>Section <link linkend="printing-advanced-filters">How Filters - Work</link>, tries to give an overview of a filter's role in the - printing process. You should read this section to get an - understanding of what is happening “under the hood” - when LPD uses filters. This knowledge could help you anticipate - and debug problems you might encounter as you install more and - more filters on each of your printers.</para> - </listitem> - - <listitem> - <para>LPD expects every printer to be able to print plain text by - default. This presents a problem for PostScript (or other - language-based printers) which cannot directly print plain text. - Section <link - linkend="printing-advanced-if-conversion">Accommodating - Plain Text Jobs on PostScript Printers</link> tells you what you - should do to overcome this problem. I recommend reading this - section if you have a PostScript printer.</para> - </listitem> - - <listitem> - <para>PostScript is a popular output format for many programs. Even - some people (myself included) write PostScript code directly. But - PostScript printers are expensive. Section <link - linkend="printing-advanced-ps">Simulating PostScript on - Non-PostScript Printers</link> tells how you can further modify - a printer's text filter to accept and print PostScript data on a - <emphasis>non-PostScript</emphasis> printer. I recommend reading - this section if you do not have a PostScript printer.</para> - </listitem> - - <listitem> - <para>Section <link - linkend="printing-advanced-convfilters">Conversion - Filters</link> tells about a way you can automate the conversion - of specific file formats, such as graphic or typesetting data, - into formats your printer can understand. After reading this - section, you should be able to set up your printers such that - users can type <command>lpr -t</command> to print troff data, or - <command>lpr -d</command> to print TeX DVI data, or <command>lpr - -v</command> to print raster image data, and so forth. I - recommend reading this section.</para> - </listitem> - - <listitem> - <para>Section <link linkend="printing-advanced-of">Output - Filters</link> tells all about a not often used feature of LPD: - output filters. Unless you are printing header pages (see <link - linkend="printing-advanced-header-pages">Header Pages</link>), - you can probably skip that section altogether.</para> - </listitem> - - <listitem> - <para>Section <link linkend="printing-advanced-lpf">lpf: a Text - Filter</link> describes <command>lpf</command>, a fairly - complete if simple text filter for line printers (and laser - printers that act like line printers) that comes with FreeBSD. If - you need a quick way to get printer accounting working for plain - text, or if you have a printer which emits smoke when it sees - backspace characters, you should definitely consider - <command>lpf</command>.</para> - </listitem> - </itemizedlist> - - <sect3 id="printing-advanced-filters"> - <title>How Filters Work</title> - - <para>As mentioned before, a filter is an executable program started - by LPD to handle the device-dependent part of communicating with the - printer.</para> - - <para>When LPD wants to print a file in a job, it starts a filter - program. It sets the filter's standard input to the file to print, - its standard output to the printer, and its standard error to the - error logging file (specified in the <literal>lf</literal> - capability in <filename>/etc/printcap</filename>, or - <filename>/dev/console</filename> by default).</para> - - <para>Which filter LPD starts and the filter's arguments depend on - what is listed in the <filename>/etc/printcap</filename> file and - what arguments the user specified for the job on the - &man.lpr.1; command line. For example, if the user typed - <command>lpr -t</command>, LPD would start the troff filter, listed - in the <literal>tf</literal> capability for the destination printer. - If the user wanted to print plain text, it would start the - <literal>if</literal> filter (this is mostly true: see <link - linkend="printing-advanced-of">Output Filters</link> for - details).</para> - - <para>There are three kinds of filters you can specify in - <filename>/etc/printcap</filename>:</para> - - <itemizedlist> - <listitem> - <para>The <emphasis>text filter</emphasis>, confusingly called the - <emphasis>input filter</emphasis> in LPD documentation, handles - regular text printing. Think of it as the default filter. LPD - expects every printer to be able to print plain text by default, - and it is the text filter's job to make sure backspaces, tabs, - or other special characters do not confuse the printer. If you - are in an environment where you have to account for printer - usage, the text filter must also account for pages printed, - usually by counting the number of lines printed and comparing - that to the number of lines per page the printer supports. The - text filter is started with the following argument list: - - <cmdsynopsis> - <command>filter-name</command> - <arg>-c</arg> - <arg choice="plain">-w<replaceable>width</replaceable></arg> - <arg choice="plain">-l<replaceable>length</replaceable></arg> - <arg choice="plain">-i<replaceable>indent</replaceable></arg> - <arg choice="plain">-n <replaceable>login</replaceable></arg> - <arg choice="plain">-h <replaceable>host</replaceable></arg> - <arg choice="plain"><replaceable>acct-file</replaceable></arg> - </cmdsynopsis> - - where - - <variablelist> - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>appears if the job's submitted with <command>lpr - -l</command></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>width</replaceable></term> - - <listitem> - <para>is the value from the <literal>pw</literal> (page - width) capability specified in - <filename>/etc/printcap</filename>, default 132</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>length</replaceable></term> - - <listitem> - <para>is the value from the <literal>pl</literal> (page - length) capability, default 66</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>indent</replaceable></term> - - <listitem> - <para>is the amount of the indentation from <command>lpr - -i</command>, default 0</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>login</replaceable></term> - - <listitem> - <para>is the account name of the user printing the - file</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>host</replaceable></term> - - <listitem> - <para>is the host name from which the job was - submitted</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>acct-file</replaceable></term> - - <listitem> - <para>is the name of the accounting file from the - <literal>af</literal> capability.</para> - </listitem> - </varlistentry> - </variablelist> - </para> - </listitem> - - <listitem> - <para>A <emphasis>conversion filter</emphasis> converts a specific - file format into one the printer can render onto paper. For - example, ditroff typesetting data cannot be directly printed, - but you can install a conversion filter for ditroff files to - convert the ditroff data into a form the printer can digest and - print. Section <link - linkend="printing-advanced-convfilters">Conversion - Filters</link> tells all about them. Conversion filters also - need to do accounting, if you need printer accounting. - Conversion filters are started with the following arguments: - - <cmdsynopsis> - <command>filter-name</command> - <arg - choice="plain">-x<replaceable>pixel-width</replaceable></arg> - <arg choice="plain">-y<replaceable>pixel-height</replaceable></arg> - <arg choice="plain">-n <replaceable>login</replaceable></arg> - <arg choice="plain">-h <replaceable>host</replaceable></arg> - <arg choice="plain"><replaceable>acct-file</replaceable></arg> - </cmdsynopsis> - - where <replaceable>pixel-width</replaceable> is the value - from the <literal>px</literal> capability (default 0) and - <replaceable>pixel-height</replaceable> is the value from the - <literal>py</literal> capability (default 0).</para> - </listitem> - - <listitem> - <para>The <emphasis>output filter</emphasis> is used only if there - is no text filter, or if header pages are enabled. In my - experience, output filters are rarely used. Section <link - linkend="printing-advanced-of">Output Filters</link> describe - them. There are only two arguments to an output filter: - - <cmdsynopsis> - <command>filter-name</command> - <arg choice="plain">-w<replaceable>width</replaceable></arg> - <arg choice="plain">-l<replaceable>length</replaceable></arg> - </cmdsynopsis> - - which are identical to the text filters <option>-w</option> and - <option>-l</option> arguments.</para> - </listitem> - </itemizedlist> - - <para>Filters should also <emphasis>exit</emphasis> with the - following exit status:</para> - - <variablelist> - <varlistentry> - <term>exit 0</term> - - <listitem> - <para>If the filter printed the file successfully.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>exit 1</term> - - <listitem> - <para>If the filter failed to print the file but wants LPD to - try to print the file again. LPD will restart a filter if it - exits with this status.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>exit 2</term> - - <listitem> - <para>If the filter failed to print the file and does not want - LPD to try again. LPD will throw out the file.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The text filter that comes with the FreeBSD release, - <filename>/usr/libexec/lpr/lpf</filename>, takes advantage of the - page width and length arguments to determine when to send a form - feed and how to account for printer usage. It uses the login, host, - and accounting file arguments to make the accounting entries.</para> - - <para>If you are shopping for filters, see if they are LPD-compatible. - If they are, they must support the argument lists described above. - If you plan on writing filters for general use, then have them - support the same argument lists and exit codes.</para> - </sect3> - - <sect3 id="printing-advanced-if-conversion"> - <title>Accommodating Plain Text Jobs on PostScript Printers</title> - - <para>If you are the only user of your computer and PostScript (or - other language-based) printer, and you promise to never send plain - text to your printer and to never use features of various programs - that will want to send plain text to your printer, then you do not - need to worry about this section at all.</para> - - <para>But, if you would like to send both PostScript and plain text - jobs to the printer, then you are urged to augment your printer - setup. To do so, we have the text filter detect if the arriving job - is plain text or PostScript. All PostScript jobs must start with - <literal>%!</literal> (for other printer languages, see your printer - documentation). If those are the first two characters in the job, - we have PostScript, and can pass the rest of the job directly. If - those are not the first two characters in the file, then the filter - will convert the text into PostScript and print the result.</para> - - <para>How do we do this?</para> - - <para>If you have got a serial printer, a great way to do it is to - install <command>lprps</command>. <command>lprps</command> is a - PostScript printer filter which performs two-way communication with - the printer. It updates the printer's status file with verbose - information from the printer, so users and administrators can see - exactly what the state of the printer is (such as <errorname>toner - low</errorname> or <errorname>paper jam</errorname>). But more - importantly, it includes a program called <command>psif</command> - which detects whether the incoming job is plain text and calls - <command>textps</command> (another program that comes with - <command>lprps</command>) to convert it to PostScript. It then uses - <command>lprps</command> to send the job to the printer.</para> - - <para><command>lprps</command> is part of the FreeBSD ports collection - (see <link linkend="ports">The Ports Collection</link>). You can - fetch, build and install it yourself, of course. After installing - <command>lprps</command>, just specify the pathname to the - <command>psif</command> program that is part of - <command>lprps</command>. If you installed <command>lprps</command> - from the ports collection, use the following in the serial - PostScript printer's entry in - <filename>/etc/printcap</filename>:</para> - - <programlisting> -:if=/usr/local/libexec/psif:</programlisting> - - <para>You should also specify the <literal>rw</literal> capability; - that tells LPD to open the printer in read-write mode.</para> - - <para>If you have a parallel PostScript printer (and therefore cannot - use two-way communication with the printer, which - <command>lprps</command> needs), you can use the following shell - script as the text filter:</para> - - <programlisting> -#!/bin/sh -# -# psif - Print PostScript or plain text on a PostScript printer -# Script version; NOT the version that comes with lprps -# Installed in /usr/local/libexec/psif -# - -read first_line -first_two_chars=`expr "$first_line" : '\(..\)'` - -if [ "$first_two_chars" = "%!" ]; then - # - # PostScript job, print it. - # - echo "$first_line" && cat && printf "\004" && exit 0 - exit 2 -else - # - # Plain text, convert it, then print it. - # - ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0 - exit 2 -fi</programlisting> - - <para>In the above script, <command>textps</command> is a program we - installed separately to convert plain text to PostScript. You can - use any text-to-PostScript program you wish. The FreeBSD ports - collection (see <link linkend="ports">The Ports Collection</link>) - includes a full featured text-to-PostScript program called - <literal>a2ps</literal> that you might want to investigate.</para> - </sect3> - - <sect3 id="printing-advanced-ps"> - <title>Simulating PostScript on Non-PostScript Printers</title> - - <para>PostScript is the <emphasis>de facto</emphasis> standard for - high quality typesetting and printing. PostScript is, however, an - <emphasis>expensive</emphasis> standard. Thankfully, Alladin - Enterprises has a free PostScript work-alike called - <application>Ghostscript</application> that runs with FreeBSD. - Ghostscript can read most PostScript files and can render their - pages onto a variety of devices, including many brands of - non-PostScript printers. By installing Ghostscript and using a - special text filter for your printer, you can make your - non-PostScript printer act like a real PostScript printer.</para> - - <para>Ghostscript should be in the FreeBSD ports collection, if you - would like to install it from there. You can fetch, build, and - install it quite easily yourself, as well.</para> - - <para>To simulate PostScript, we have the text filter detect if it is - printing a PostScript file. If it is not, then the filter will pass - the file directly to the printer; otherwise, it will use Ghostscript - to first convert the file into a format the printer will - understand.</para> - - <para>Here is an example: the following script is a text filter - for Hewlett Packard DeskJet 500 printers. For other printers, - substitute the <option>-sDEVICE</option> argument to the - <command>gs</command> (Ghostscript) command. (Type <command>gs - -h</command> to get a list of devices the current installation of - Ghostscript supports.)</para> - - <programlisting> -#!/bin/sh -# -# ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500 -# Installed in /usr/local/libexec/hpif - -# -# Treat LF as CR+LF: -# -printf "\033&k2G" || exit 2 - -# -# Read first two characters of the file -# -read first_line -first_two_chars=`expr "$first_line" : '\(..\)'` - -if [ "$first_two_chars" = "%!" ]; then - # - # It is PostScript; use Ghostscript to scan-convert and print it. - # - # Note that PostScript files are actually interpreted programs, - # and those programs are allowed to write to stdout, which will - # mess up the printed output. So, we redirect stdout to stderr - # and then make descriptor 3 go to stdout, and have Ghostscript - # write its output there. Exercise for the clever reader: - # capture the stderr output from Ghostscript and mail it back to - # the user originating the print job. - # - exec 3>&1 1>&2 - /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \ - -sOutputFile=/dev/fd/3 - && exit 0 - - # - /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 -sOutputFile=- - \ - && exit 0 -else - # - # Plain text or HP/PCL, so just print it directly; print a form - # at the end to eject the last page. - # - echo $first_line && cat && printf "\033&l0H" && exit 0 -fi - -exit 2</programlisting> - - <para>Finally, you need to notify LPD of the filter via the - <literal>if</literal> capability:</para> - - <programlisting> -:if=/usr/local/libexec/hpif:</programlisting> - - <para>That is it. You can type <command>lpr plain.text</command> and - <filename>lpr whatever.ps</filename> and both should print - successfully.</para> - </sect3> - - <sect3 id="printing-advanced-convfilters"> - <title>Conversion Filters</title> - - <para>After completing the simple setup described in <link - linkend="printing-simple">Simple Printer Setup</link>, the first - thing you will probably want to do is install conversion filters for - your favorite file formats (besides plain ASCII text).</para> - - <sect4> - <title>Why Install Conversion Filters?</title> - - <para>Conversion filters make printing various kinds of files easy. - As an example, suppose we do a lot of work with the TeX - typesetting system, and we have a PostScript printer. Every time - we generate a DVI file from TeX, we cannot print it directly until - we convert the DVI file into PostScript. The command sequence - goes like this:</para> - - <screen>&prompt.user; <userinput>dvips seaweed-analysis.dvi</userinput> -&prompt.user; <userinput>lpr seaweed-analysis.ps</userinput></screen> - - <para>By installing a conversion filter for DVI files, we can skip - the hand conversion step each time by having LPD do it for us. - Now, each time we get a DVI file, we are just one step away from - printing it:</para> - - <screen>&prompt.user; <userinput>lpr -d seaweed-analysis.dvi</userinput></screen> - - <para>We got LPD to do the DVI file conversion for us by specifying - the <option>-d</option> option. Section <link - linkend="printing-lpr-options-format">Formatting and Conversion - Options</link> lists the conversion options.</para> - - <para>For each of the conversion options you want a printer to - support, install a <emphasis>conversion filter</emphasis> and - specify its pathname in <filename>/etc/printcap</filename>. A - conversion filter is like the text filter for the simple printer - setup (see section <link linkend="printing-textfilter">Installing - the Text Filter</link>) except that instead of printing plain - text, the filter converts the file into a format the printer can - understand.</para> - </sect4> - - <sect4> - <title>Which Conversions Filters Should I Install?</title> - - <para>You should install the conversion filters you expect to use. - If you print a lot of DVI data, then a DVI conversion filter is in - order. If you have got plenty of troff to print out, then you - probably want a troff filter.</para> - - <para>The following table summarizes the filters that LPD works - with, their capability entries for the - <filename>/etc/printcap</filename> file, and how to invoke them - with the <command>lpr</command> command:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>File type</entry> - <entry><filename>/etc/printcap</filename> capability</entry> - <entry><command>lpr</command> option</entry> - </row> - </thead> - - <tbody> - <row> - <entry>cifplot</entry> - <entry><literal>cf</literal></entry> - <entry><option>-c</option></entry> - </row> - - <row> - <entry>DVI</entry> - <entry><literal>df</literal></entry> - <entry><option>-d</option></entry> - </row> - - <row> - <entry>plot</entry> - <entry><literal>gf</literal></entry> - <entry><option>-g</option></entry> - </row> - - <row> - <entry>ditroff</entry> - <entry><literal>nf</literal></entry> - <entry><option>-n</option></entry> - </row> - - <row> - <entry>FORTRAN text</entry> - <entry><literal>rf</literal></entry> - <entry><option>-f</option></entry> - </row> - - <row> - <entry>troff</entry> - <entry><literal>rf</literal></entry> - <entry><option>-f</option></entry> - </row> - - <row> - <entry>raster</entry> - <entry><literal>vf</literal></entry> - <entry><option>-v</option></entry> - </row> - - <row> - <entry>plain text</entry> - <entry><literal>if</literal></entry> - <entry>none, <option>-p</option>, or - <option>-l</option></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>In our example, using <command>lpr -d</command> means the - printer needs a <literal>df</literal> capability in its entry in - <filename>/etc/printcap</filename>.</para> - - <para>Despite what others might contend, formats like FORTRAN text - and plot are probably obsolete. At your site, you can give new - meanings to these or any of the formatting options just by - installing custom filters. For example, suppose you would like to - directly print Printerleaf files (files from the Interleaf desktop - publishing program), but will never print plot files. You could - install a Printerleaf conversion filter under the - <literal>gf</literal> capability and then educate your users that - <command>lpr -g</command> mean “print Printerleaf - files.”</para> - </sect4> - - <sect4> - <title>Installing Conversion Filters</title> - - <para>Since conversion filters are programs you install outside of - the base FreeBSD installation, they should probably go under - <filename>/usr/local</filename>. The directory - <filename>/usr/local/libexec</filename> is a popular location, - since they are specialized programs that only LPD will run; - regular users should not ever need to run them.</para> - - <para>To enable a conversion filter, specify its pathname under the - appropriate capability for the destination printer in - <filename>/etc/printcap</filename>.</para> - - <para>In our example, we will add the DVI conversion filter to the - entry for the printer named <literal>bamboo</literal>. Here is - the example <filename>/etc/printcap</filename> file again, with - the new <literal>df</literal> capability for the printer - <literal>bamboo</literal>.</para> - - <programlisting> -# -# /etc/printcap for host rose - added df filter for bamboo -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>The DVI filter is a shell script named - <filename>/usr/local/libexec/psdf</filename>. Here is that - script:</para> - - <programlisting> -#!bin/sh -# -# psdf - DVI to PostScript printer filter -# Installed in /usr/local/libexec/psdf -# -# Invoked by lpd when user runs lpr -d -# -exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"</programlisting> - - <para>This script runs <command>dvips</command> in filter mode (the - <option>-f</option> argument) on standard input, which is the job - to print. It then starts the PostScript printer filter - <command>lprps</command> (see section <link - linkend="printing-advanced-if-conversion">Accommodating Plain - Text Jobs on PostScript Printers</link>) with the arguments LPD - passed to this script. <command>lprps</command> will use those - arguments to account for the pages printed.</para> - </sect4> - - <sect4> - <title>More Conversion Filter Examples</title> - - <para>Since there is no fixed set of steps to install conversion - filters, let me instead provide more examples. Use these as - guidance to making your own filters. Use them directly, if - appropriate.</para> - - <para>This example script is a raster (well, GIF file, actually) - conversion filter for a Hewlett Packard LaserJet III-Si - printer:</para> - - <programlisting> -#!/bin/sh -# -# hpvf - Convert GIF files into HP/PCL, then print -# Installed in /usr/local/libexec/hpvf - -PATH=/usr/X11R6/bin:$PATH; export PATH -giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \ - && exit 0 \ - || exit 2</programlisting> - - <para>It works by converting the GIF file into a portable anymap, - converting that into a portable graymap, converting that into a - portable bitmap, and converting that into LaserJet/PCL-compatible - data.</para> - - <para>Here is the <filename>/etc/printcap</filename> file with an - entry for a printer using the above filter:</para> - - <programlisting> -# -# /etc/printcap for host orchid -# -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\ - :if=/usr/local/libexec/hpif:\ - :vf=/usr/local/libexec/hpvf:</programlisting> - - <para>The following script is a conversion filter for troff data - from the groff typesetting system for the PostScript printer named - <literal>bamboo</literal>:</para> - - <programlisting> -#!/bin/sh -# -# pstf - Convert groff's troff data into PS, then print. -# Installed in /usr/local/libexec/pstf -# -exec grops | /usr/local/libexec/lprps "$@"</programlisting> - - <para>The above script makes use of <command>lprps</command> again - to handle the communication with the printer. If the printer were - on a parallel port, we would use this script instead:</para> - - <programlisting> -#!/bin/sh -# -# pstf - Convert groff's troff data into PS, then print. -# Installed in /usr/local/libexec/pstf -# -exec grops</programlisting> - - <para>That is it. Here is the entry we need to add to - <filename>/etc/printcap</filename> to enable the filter:</para> - - <programlisting> -:tf=/usr/local/libexec/pstf:</programlisting> - - <para>Here is an example that might make old hands at FORTRAN blush. - It is a FORTRAN-text filter for any printer that can directly - print plain text. We will install it for the printer - <literal>teak</literal>:</para> - - <programlisting> -#!/bin/sh -# -# hprf - FORTRAN text filter for LaserJet 3si: -# Installed in /usr/local/libexec/hprf -# - -printf "\033&k2G" && fpr && printf "\033&l0H" && exit 0 -exit 2</programlisting> - - <para>And we will add this line to the - <filename>/etc/printcap</filename> for the printer - <literal>teak</literal> to enable this filter:</para> - - <programlisting> -:rf=/usr/local/libexec/hprf:</programlisting> - - <para>Here is one final, somewhat complex example. We will add a - DVI filter to the LaserJet printer <literal>teak</literal> - introduced earlier. First, the easy part: updating - <filename>/etc/printcap</filename> with the location of the DVI - filter:</para> - - <programlisting> -:df=/usr/local/libexec/hpdf:</programlisting> - - <para>Now, for the hard part: making the filter. For that, we need - a DVI-to-LaserJet/PCL conversion program. The FreeBSD ports - collection (see <link linkend="ports">The Ports Collection</link>) - has one: <command>dvi2xx</command> is the name of the package. - Installing this package gives us the program we need, - <command>dvilj2p</command>, which converts DVI into LaserJet IIp, - LaserJet III, and LaserJet 2000 compatible codes.</para> - - <para><command>dvilj2p</command> makes the filter - <command>hpdf</command> quite complex since - <command>dvilj2p</command> cannot read from standard input. It - wants to work with a filename. What is worse, the filename has to - end in <filename>.dvi</filename> so using - <filename>/dev/fd/0</filename> for standard input is problematic. - We can get around that problem by linking (symbolically) a - temporary file name (one that ends in <filename>.dvi</filename>) - to <filename>/dev/fd/0</filename>, thereby forcing - <command>dvilj2p</command> to read from standard input.</para> - - <para>The only other fly in the ointment is the fact that we cannot - use <filename>/tmp</filename> for the temporary link. Symbolic - links are owned by user and group <username>bin</username>. The - filter runs as user <username>daemon</username>. And the - <filename>/tmp</filename> directory has the sticky bit set. The - filter can create the link, but it will not be able clean up when - done and remove it since the link will belong to a different - user.</para> - - <para>Instead, the filter will make the symbolic link in the current - working directory, which is the spooling directory (specified by - the <literal>sd</literal> capability in - <filename>/etc/printcap</filename>). This is a perfect place for - filters to do their work, especially since there is (sometimes) - more free disk space in the spooling directory than under - <filename>/tmp</filename>.</para> - - <para>Here, finally, is the filter:</para> - - <programlisting> -#!/bin/sh -# -# hpdf - Print DVI data on HP/PCL printer -# Installed in /usr/local/libexec/hpdf - -PATH=/usr/local/bin:$PATH; export PATH - -# -# Define a function to clean up our temporary files. These exist -# in the current directory, which will be the spooling directory -# for the printer. -# -cleanup() { - rm -f hpdf$$.dvi -} - -# -# Define a function to handle fatal errors: print the given message -# and exit 2. Exiting with 2 tells LPD to do not try to reprint the -# job. -# -fatal() { - echo "$@" 1>&2 - cleanup - exit 2 -} - -# -# If user removes the job, LPD will send SIGINT, so trap SIGINT -# (and a few other signals) to clean up after ourselves. -# -trap cleanup 1 2 15 - -# -# Make sure we are not colliding with any existing files. -# -cleanup - -# -# Link the DVI input file to standard input (the file to print). -# -ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0" - -# -# Make LF = CR+LF -# -printf "\033&k2G" || fatal "Cannot initialize printer" - -# -# Convert and print. Return value from dvilj2p does not seem to be -# reliable, so we ignore it. -# -dvilj2p -M1 -q -e- dfhp$$.dvi - -# -# Clean up and exit -# -cleanup -exit 0</programlisting> - </sect4> - - <sect4 id="printing-advanced-autoconv"> - <title>Automated Conversion: An Alternative To Conversion - Filters</title> - - <para>All these conversion filters accomplish a lot for your - printing environment, but at the cost forcing the user to specify - (on the &man.lpr.1; command line) which one to use. - If your users are not particularly computer literate, having to - specify a filter option will become annoying. What is worse, - though, is that an incorrectly specified filter option may run a - filter on the wrong type of file and cause your printer to spew - out hundreds of sheets of paper.</para> - - <para>Rather than install conversion filters at all, you might want - to try having the text filter (since it is the default filter) - detect the type of file it has been asked to print and then - automatically run the right conversion filter. Tools such as - <command>file</command> can be of help here. Of course, it will - be hard to determine the differences between - <emphasis>some</emphasis> file types—and, of course, you can - still provide conversion filters just for them.</para> - - <para>The FreeBSD ports collection has a text filter that performs - automatic conversion called <command>apsfilter</command>. It can - detect plain text, PostScript, and DVI files, run the proper - conversions, and print.</para> - </sect4> - </sect3> - - <sect3 id="printing-advanced-of"> - <title>Output Filters</title> - - <para>The LPD spooling system supports one other type of filter that - we have not yet explored: an output filter. An output filter is - intended for printing plain text only, like the text filter, but - with many simplifications. If you are using an output filter but no - text filter, then:</para> - - <itemizedlist> - <listitem> - <para>LPD starts an output filter once for the entire job instead - of once for each file in the job.</para> - </listitem> - - <listitem> - <para>LPD does not make any provision to identify the start or the - end of files within the job for the output filter.</para> - </listitem> - - <listitem> - <para>LPD does not pass the user's login or host to the filter, so - it is not intended to do accounting. In fact, it gets only two - arguments:</para> - - <cmdsynopsis> - <command>filter-name</command> - <arg choice="plain">-w<replaceable>width</replaceable></arg> - <arg choice="plain">-l<replaceable>length</replaceable></arg> - </cmdsynopsis> - - <para>Where <replaceable>width</replaceable> is from the - <literal>pw</literal> capability and - <replaceable>length</replaceable> is from the - <literal>pl</literal> capability for the printer in - question.</para> - </listitem> - </itemizedlist> - - <para>Do not be seduced by an output filter's simplicity. If you - would like each file in a job to start on a different page an output - filter <emphasis>will not work</emphasis>. Use a text filter (also - known as an input filter); see section <link - linkend="printing-textfilter">Installing the Text Filter</link>. - Furthermore, an output filter is actually <emphasis>more - complex</emphasis> in that it has to examine the byte stream being - sent to it for special flag characters and must send signals to - itself on behalf of LPD.</para> - - <para>However, an output filter is <emphasis>necessary</emphasis> if - you want header pages and need to send escape sequences or other - initialization strings to be able to print the header page. (But it - is also <emphasis>futile</emphasis> if you want to charge header - pages to the requesting user's account, since LPD does not give any - user or host information to the output filter.)</para> - - <para>On a single printer, LPD allows both an output filter and text - or other filters. In such cases, LPD will start the output filter - to print the header page (see section <link - linkend="printing-advanced-header-pages">Header Pages</link>) - only. LPD then expects the output filter to <emphasis>stop - itself</emphasis> by sending two bytes to the filter: ASCII 031 - followed by ASCII 001. When an output filter sees these two bytes - (031, 001), it should stop by sending SIGSTOP to itself. When LPD's - done running other filters, it will restart the output filter by - sending SIGCONT to it.</para> - - <para>If there is an output filter but <emphasis>no</emphasis> text - filter and LPD is working on a plain text job, LPD uses the output - filter to do the job. As stated before, the output filter will - print each file of the job in sequence with no intervening form - feeds or other paper advancement, and this is probably - <emphasis>not</emphasis> what you want. In almost all cases, you - need a text filter.</para> - - <para>The program <command>lpf</command>, which we introduced earlier - as a text filter, can also run as an output filter. If you need a - quick-and-dirty output filter but do not want to write the byte - detection and signal sending code, try <command>lpf</command>. You - can also wrap <command>lpf</command> in a shell script to handle any - initialization codes the printer might require.</para> - </sect3> - - <sect3 id="printing-advanced-lpf"> - <title><command>lpf</command>: a Text Filter</title> - - <para>The program <filename>/usr/libexec/lpr/lpf</filename> that comes - with FreeBSD binary distribution is a text filter (input filter) - that can indent output (job submitted with <command>lpr - -i</command>), allow literal characters to pass (job submitted - with <command>lpr -l</command>), adjust the printing position for - backspaces and tabs in the job, and account for pages printed. It - can also act like an output filter.</para> - - <para><command>lpf</command> is suitable for many printing - environments. And although it has no capability to send - initialization sequences to a printer, it is easy to write a shell - script to do the needed initialization and then execute - <command>lpf</command>.</para> - - <para>In order for <command>lpf</command> to do page accounting - correctly, it needs correct values filled in for the - <literal>pw</literal> and <literal>pl</literal> capabilities in the - <filename>/etc/printcap</filename> file. It uses these values to - determine how much text can fit on a page and how many pages were in - a user's job. For more information on printer accounting, see <link - linkend="printing-advanced-acct">Accounting for Printer - Usage</link>.</para> - </sect3> - </sect2> - - <sect2 id="printing-advanced-header-pages"> - <title>Header Pages</title> - - <para>If you have <emphasis>lots</emphasis> of users, all of them using - various printers, then you probably want to consider <emphasis>header - pages</emphasis> as a necessary evil.</para> - - <para>Header pages, also known as <emphasis>banner</emphasis> or - <emphasis>burst pages</emphasis> identify to whom jobs belong after - they are printed. They are usually printed in large, bold letters, - perhaps with decorative borders, so that in a stack of printouts they - stand out from the real documents that comprise users' jobs. They - enable users to locate their jobs quickly. The obvious drawback to a - header page is that it is yet one more sheet that has to be printed - for every job, their ephemeral usefulness lasting not more than a few - minutes, ultimately finding themselves in a recycling bin or rubbish - heap. (Note that header pages go with each job, not each file in a - job, so the paper waste might not be that bad.)</para> - - <para>The LPD system can provide header pages automatically for your - printouts <emphasis>if</emphasis> your printer can directly print - plain text. If you have a PostScript printer, you will need an - external program to generate the header page; see <link - linkend="printing-advanced-header-pages-ps">Header Pages on - PostScript Printers</link>.</para> - - <sect3 id="printing-advanced-header-pages-enabling"> - <title>Enabling Header Pages</title> - - <para>In the <link linkend="printing-simple">Simple Printer - Setup</link>, we turned off header pages by specifying - <literal>sh</literal> (meaning “suppress header”) in the - <filename>/etc/printcap</filename> file. To enable header pages for - a printer, just remove the <literal>sh</literal> capability.</para> - - <para>Sounds too easy, right?</para> - - <para>You are right. You <emphasis>might</emphasis> have to provide - an output filter to send initialization strings to the printer. - Here is an example output filter for Hewlett Packard PCL-compatible - printers:</para> - - <programlisting> -#!/bin/sh -# -# hpof - Output filter for Hewlett Packard PCL-compatible printers -# Installed in /usr/local/libexec/hpof - -printf "\033&k2G" || exit 2 -exec /usr/libexec/lpr/lpf</programlisting> - - <para>Specify the path to the output filter in the - <literal>of</literal> capability. See <link - linkend="printing-advanced-of">Output Filters</link> for more - information.</para> - - <para>Here is an example <filename>/etc/printcap</filename> file for - the printer <literal>teak</literal> that we introduced earlier; we - enabled header pages and added the above output filter:</para> - - <programlisting> -# -# /etc/printcap for host orchid -# -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\ - :if=/usr/local/libexec/hpif:\ - :vf=/usr/local/libexec/hpvf:\ - :of=/usr/local/libexec/hpof:</programlisting> - - <para>Now, when users print jobs to <literal>teak</literal>, they get - a header page with each job. If users want to spend time searching - for their printouts, they can suppress header pages by submitting - the job with <command>lpr -h</command>; see <link - linkend="printing-lpr-options-misc">Header Page Options</link> for - more &man.lpr.1; options.</para> - - <note> - <para>LPD prints a form feed character after the header page. If - your printer uses a different character or sequence of characters - to eject a page, specify them with the <literal>ff</literal> - capability in <filename>/etc/printcap</filename>.</para> - </note> - </sect3> - - <sect3 id="printing-advanced-header-pages-controlling"> - <title>Controlling Header Pages</title> - - <para>By enabling header pages, LPD will produce a <emphasis>long - header</emphasis>, a full page of large letters identifying the - user, host, and job. Here is an example (kelly printed the job - named outline from host rose):</para> - - <programlisting> - k ll ll - k l l - k l l - k k eeee l l y y - k k e e l l y y - k k eeeeee l l y y - kk k e l l y y - k k e e l l y yy - k k eeee lll lll yyy y - y - y y - yyyy - - - ll - t l i - t l - oooo u u ttttt l ii n nnn eeee - o o u u t l i nn n e e - o o u u t l i n n eeeeee - o o u u t l i n n e - o o u uu t t l i n n e e - oooo uuu u tt lll iii n n eeee - - - - - - - - - - r rrr oooo ssss eeee - rr r o o s s e e - r o o ss eeeeee - r o o ss e - r o o s s e e - r oooo ssss eeee - - - - - - - - Job: outline - Date: Sun Sep 17 11:04:58 1995</programlisting> - - <para>LPD appends a form feed after this text so the job starts on a - new page (unless you have <literal>sf</literal> (suppress form - feeds) in the destination printer's entry in - <filename>/etc/printcap</filename>).</para> - - <para>If you prefer, LPD can make a <emphasis>short header</emphasis>; - specify <literal>sb</literal> (short banner) in the - <filename>/etc/printcap</filename> file. The header page will look - like this:</para> - - <programlisting> -rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995</programlisting> - - <para>Also by default, LPD prints the header page first, then the job. - To reverse that, specify <literal>hl</literal> (header last) in - <filename>/etc/printcap</filename>.</para> - </sect3> - - <sect3 id="printing-advanced-header-pages-accounting"> - <title>Accounting for Header Pages</title> - - <para>Using LPD's built-in header pages enforces a particular paradigm - when it comes to printer accounting: header pages must be - <emphasis>free of charge</emphasis>.</para> - - <para>Why?</para> - - <para>Because the output filter is the only external program that will - have control when the header page is printed that could do - accounting, and it is not provided with any <emphasis>user or - host</emphasis> information or an accounting file, so it has no - idea whom to charge for printer use. It is also not enough to just - “add one page” to the text filter or any of the - conversion filters (which do have user and host information) since - users can suppress header pages with <command>lpr -h</command>. - They could still be charged for header pages they did not print. - Basically, <command>lpr -h</command> will be the preferred option of - environmentally-minded users, but you cannot offer any incentive to - use it.</para> - - <para>It is <emphasis>still not enough</emphasis> to have each of the - filters generate their own header pages (thereby being able to - charge for them). If users wanted the option of suppressing the - header pages with <command>lpr -h</command>, they will still get - them and be charged for them since LPD does not pass any knowledge - of the <option>-h</option> option to any of the filters.</para> - - <para>So, what are your options?</para> - - <para>You can:</para> - - <itemizedlist> - <listitem> - <para>Accept LPD's paradigm and make header pages free.</para> - </listitem> - - <listitem> - <para>Install an alternative to LPD, such as LPRng or PLP. Section - <link linkend="printing-lpd-alternatives">Alternatives to the - Standard Spooler</link> tells more about other spooling - software you can substitute for LPD.</para> - </listitem> - - <listitem> - <para>Write a <emphasis>smart</emphasis> output filter. Normally, - an output filter is not meant to do anything more than - initialize a printer or do some simple character conversion. It - is suited for header pages and plain text jobs (when there is no - text (input) filter). But, if there is a text filter for the - plain text jobs, then LPD will start the output filter only for - the header pages. And the output filter can parse the header - page text that LPD generates to determine what user and host to - charge for the header page. The only other problem with this - method is that the output filter still does not know what - accounting file to use (it is not passed the name of the file - from the <literal>af</literal> capability), but if you have a - well-known accounting file, you can hard-code that into the - output filter. To facilitate the parsing step, use the - <literal>sh</literal> (short header) capability in - <filename>/etc/printcap</filename>. Then again, all that might - be too much trouble, and users will certainly appreciate the - more generous system administrator who makes header pages - free.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3 id="printing-advanced-header-pages-ps"> - <title>Header Pages on PostScript Printers</title> - - <para>As described above, LPD can generate a plain text header page - suitable for many printers. Of course, PostScript cannot directly - print plain text, so the header page feature of LPD is - useless—or mostly so.</para> - - <para>One obvious way to get header pages is to have every conversion - filter and the text filter generate the header page. The filters - should should use the user and host arguments to generate a suitable - header page. The drawback of this method is that users will always - get a header page, even if they submit jobs with <command>lpr - -h</command>.</para> - - <para>Let us explore this method. The following script takes three - arguments (user login name, host name, and job name) and makes a - simple PostScript header page:</para> - - <programlisting> -#!/bin/sh -# -# make-ps-header - make a PostScript header page on stdout -# Installed in /usr/local/libexec/make-ps-header -# - -# -# These are PostScript units (72 to the inch). Modify for A4 or -# whatever size paper you are using: -# -page_width=612 -page_height=792 -border=72 - -# -# Check arguments -# -if [ $# -ne 3 ]; then - echo "Usage: `basename $0` <user> <host> <job>" 1>&2 - exit 1 -fi - -# -# Save these, mostly for readability in the PostScript, below. -# -user=$1 -host=$2 -job=$3 -date=`date` - -# -# Send the PostScript code to stdout. -# -exec cat <<EOF -%!PS - -% -% Make sure we do not interfere with user's job that will follow -% -save - -% -% Make a thick, unpleasant border around the edge of the paper. -% -$border $border moveto -$page_width $border 2 mul sub 0 rlineto -0 $page_height $border 2 mul sub rlineto -currentscreen 3 -1 roll pop 100 3 1 roll setscreen -$border 2 mul $page_width sub 0 rlineto closepath -0.8 setgray 10 setlinewidth stroke 0 setgray - -% -% Display user's login name, nice and large and prominent -% -/Helvetica-Bold findfont 64 scalefont setfont -$page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto -($user) show - -% -% Now show the boring particulars -% -/Helvetica findfont 14 scalefont setfont -/y 200 def -[ (Job:) (Host:) (Date:) ] { -200 y moveto show /y y 18 sub def } -forall - -/Helvetica-Bold findfont 14 scalefont setfont -/y 200 def -[ ($job) ($host) ($date) ] { - 270 y moveto show /y y 18 sub def -} forall - -% -% That is it -% -restore -showpage -EOF</programlisting> - - <para>Now, each of the conversion filters and the text filter can call - this script to first generate the header page, and then print the - user's job. Here is the DVI conversion filter from earlier in this - document, modified to make a header page:</para> - - <programlisting> -#!/bin/sh -# -# psdf - DVI to PostScript printer filter -# Installed in /usr/local/libexec/psdf -# -# Invoked by lpd when user runs lpr -d -# - -orig_args="$@" - -fail() { - echo "$@" 1>&2 - exit 2 -} - -while getopts "x:y:n:h:" option; do - case $option in - x|y) ;; # Ignore - n) login=$OPTARG ;; - h) host=$OPTARG ;; - *) echo "LPD started `basename $0` wrong." 1>&2 - exit 2 - ;; - esac -done - -[ "$login" ] || fail "No login name" -[ "$host" ] || fail "No host name" - -( /usr/local/libexec/make-ps-header $login $host "DVI File" - /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args</programlisting> - - <para>Notice how the filter has to parse the argument list in order to - determine the user and host name. The parsing for the other - conversion filters is identical. The text filter takes a slightly - different set of arguments, though (see section <link - linkend="printing-advanced-filters">How Filters - Work</link>).</para> - - <para>As we have mentioned before, the above scheme, though fairly - simple, disables the “suppress header page” option (the - <option>-h</option> option) to <command>lpr</command>. If users - wanted to save a tree (or a few pennies, if you charge for header - pages), they would not be able to do so, since every filter's going - to print a header page with every job.</para> - - <para>To allow users to shut off header pages on a per-job basis, you - will need to use the trick introduced in section <link - linkend="printing-advanced-header-pages-accounting">Accounting for - Header Pages</link>: write an output filter that parses the - LPD-generated header page and produces a PostScript version. If the - user submits the job with <command>lpr -h</command>, then LPD will - not generate a header page, and neither will your output filter. - Otherwise, your output filter will read the text from LPD and send - the appropriate header page PostScript code to the printer.</para> - - <para>If you have a PostScript printer on a serial line, you can make - use of <command>lprps</command>, which comes with an output filter, - <command>psof</command>, which does the above. Note that - <command>psof</command> does not charge for header pages.</para> - </sect3> - </sect2> - - <sect2 id="printing-advanced-network-printers"> - <title>Networked Printing</title> - - <para>FreeBSD supports networked printing: sending jobs to remote - printers. Networked printing generally refers to two different - things:</para> - - <itemizedlist> - <listitem> - <para>Accessing a printer attached to a remote host. You install a - printer that has a conventional serial or parallel interface on - one host. Then, you set up LPD to enable access to the printer - from other hosts on the network. Section <link - linkend="printing-advanced-network-rm">Printers Installed on - Remote Hosts</link> tells how to do this.</para> - </listitem> - - <listitem> - <para>Accessing a printer attached directly to a network. The - printer has a network interface in addition (or in place of) a - more conventional serial or parallel interface. Such a printer - might work as follows:</para> - - <itemizedlist> - <listitem> - <para>It might understand the LPD protocol and can even queue - jobs from remote hosts. In this case, it acts just like a - regular host running LPD. Follow the same procedure in - section <link linkend="printing-advanced-network-rm">Printers - Installed on Remote Hosts</link> to set up such a - printer.</para> - </listitem> - - <listitem> - <para>It might support a data stream network connection. In this - case, you “attach” the printer to one host on the - network by making that host responsible for spooling jobs and - sending them to the printer. Section <link - linkend="printing-advanced-network-net-if">Printers with - Networked Data Stream Interfaces</link> gives some - suggestions on installing such printers.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - - <sect3 id="printing-advanced-network-rm"> - <title>Printers Installed on Remote Hosts</title> - - <para>The LPD spooling system has built-in support for sending jobs to - other hosts also running LPD (or are compatible with LPD). This - feature enables you to install a printer on one host and make it - accessible from other hosts. It also works with printers that have - network interfaces that understand the LPD protocol.</para> - - <para>To enable this kind of remote printing, first install a printer - on one host, the <emphasis>printer host</emphasis>, using the simple - printer setup described in <link linkend="printing-simple">Simple - Printer Setup</link>. Do any advanced setup in <link - linkend="printing-advanced">Advanced Printer Setup</link> that you - need. Make sure to test the printer and see if it works with the - features of LPD you have enabled. Also ensure that the - <emphasis>local host</emphasis> has authorization to use the LPD - service in the <emphasis>remote host</emphasis> (see <link - linkend="printing-advanced-restricting-remote">Restricting Jobs - from Remote Printers</link>).</para> - - <para>If you are using a printer with a network interface that is - compatible with LPD, then the <emphasis>printer host</emphasis> in - the discussion below is the printer itself, and the - <emphasis>printer name</emphasis> is the name you configured for the - printer. See the documentation that accompanied your printer and/or - printer-network interface.</para> - - <para>Then, on the other hosts you want to have access to the printer, - make an entry in their <filename>/etc/printcap</filename> files with - the following:</para> - - <orderedlist> - <listitem> - <para>Name the entry anything you want. For simplicity, though, - you probably want to use the same name and aliases as on the - printer host.</para> - </listitem> - - <listitem> - <para>Leave the <literal>lp</literal> capability blank, explicitly - (<literal>:lp=:</literal>).</para> - </listitem> - - <listitem> - <para>Make a spooling directory and specify its location in the - <literal>sd</literal> capability. LPD will store jobs here - before they get sent to the printer host.</para> - </listitem> - - <listitem> - <para>Place the name of the printer host in the - <literal>rm</literal> capability.</para> - </listitem> - - <listitem> - <para>Place the printer name on the <emphasis>printer - host</emphasis> in the <literal>rp</literal> - capability.</para> - </listitem> - </orderedlist> - - <para>That is it. You do not need to list conversion filters, page - dimensions, or anything else in the - <filename>/etc/printcap</filename> file.</para> - - <para>Here is an example. The host <hostid>rose</hostid> has two - printers, <literal>bamboo</literal> and <literal>rattan</literal>. - We will enable users on the host orchid to print to those printers. - Here is the <filename>/etc/printcap</filename> file for - <hostid>orchid</hostid> (back from section <link - linkend="printing-advanced-header-pages-enabling">Enabling Header - Pages</link>). It already had the entry for the printer - <literal>teak</literal>; we have added entries for the two printers - on the host rose:</para> - - <programlisting> -# -# /etc/printcap for host orchid - added (remote) printers on rose -# - -# -# teak is local; it is connected directly to orchid: -# -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\ - :if=/usr/local/libexec/ifhp:\ - :vf=/usr/local/libexec/vfhp:\ - :of=/usr/local/libexec/ofhp: - -# -# rattan is connected to rose; send jobs for rattan to rose: -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan: - -# -# bamboo is connected to rose as well: -# -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:</programlisting> - - <para>Then, we just need to make spooling directories on - <hostid>orchid</hostid>:</para> - - <screen>&prompt.root; <userinput>mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput> -&prompt.root; <userinput>chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput> -&prompt.root; <userinput>chown daemon.daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput></screen> - - <para>Now, users on <hostid>orchid</hostid> can print to - <literal>rattan</literal> and <literal>bamboo</literal>. If, for - example, a user on orchid typed - - <screen>&prompt.user; <userinput>lpr -P bamboo -d sushi-review.dvi</userinput></screen> - - the LPD system on orchid would copy the job to the spooling - directory <filename>/var/spool/lpd/bamboo</filename> and note that - it was a DVI job. As soon as the host rose has room in its - <hostid>bamboo</hostid> spooling directory, the two LPDs would - transfer the file to rose. The file would wait in rose's queue - until it was finally printed. It would be converted from DVI to - PostScript (since bamboo is a PostScript printer) on rose.</para> - </sect3> - - <sect3 id="printing-advanced-network-net-if"> - <title>Printers with Networked Data Stream Interfaces</title> - - <para>Often, when you buy a network interface card for a printer, you - can get two versions: one which emulates a spooler (the more - expensive version), or one which just lets you send data to it as if - you were using a serial or parallel port (the cheaper version). - This section tells how to use the cheaper version. For the more - expensive one, see the previous section <link - linkend="printing-advanced-network-rm">Printers Installed on - Remote Hosts</link>.</para> - - <para>The format of the <filename>/etc/printcap</filename> file lets - you specify what serial or parallel interface to use, and (if you - are using a serial interface), what baud rate, whether to use flow - control, delays for tabs, conversion of newlines, and more. But - there is no way to specify a connection to a printer that is - listening on a TCP/IP or other network port.</para> - - <para>To send data to a networked printer, you need to develop a - communications program that can be called by the text and conversion - filters. Here is one such example: the script - <command>netprint</command> takes all data on standard input and - sends it to a network-attached printer. We specify the hostname of - the printer as the first argument and the port number to which to - connect as the second argument to <command>netprint</command>. Note - that this supports one-way communication only (FreeBSD to printer); - many network printers support two-way communication, and you might - want to take advantage of that (to get printer status, perform - accounting, etc.).</para> - - <programlisting> -#!/usr/bin/perl -# -# netprint - Text filter for printer attached to network -# Installed in /usr/local/libexec/netprint -# -$#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>"; - -$printer_host = $ARGV[0]; -$printer_port = $ARGV[1]; - -require 'sys/socket.ph'; - -($ignore, $ignore, $protocol) = getprotobyname('tcp'); -($ignore, $ignore, $ignore, $ignore, $address) - = gethostbyname($printer_host); - -$sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address); - -socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol) - || die "Can't create TCP/IP stream socket: $!"; -connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!"; -while (<STDIN>) { print PRINTER; } -exit 0;</programlisting> - - <para>We can then use this script in various filters. Suppose we had - a Diablo 750-N line printer connected to the network. The printer - accepts data to print on port number 5100. The host name of the - printer is scrivener. Here is the text filter for the - printer:</para> - - <programlisting> -#!/bin/sh -# -# diablo-if-net - Text filter for Diablo printer `scrivener' listening -# on port 5100. Installed in /usr/local/libexec/diablo-if-net -# -exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</programlisting> - </sect3> - </sect2> - - <sect2 id="printing-advanced-restricting"> - <title>Restricting Printer Usage</title> - - <para>This section gives information on restricting printer usage. The - LPD system lets you control who can access a printer, both locally or - remotely, whether they can print multiple copies, how large their jobs - can be, and how large the printer queues can get.</para> - - <sect3 id="printing-advanced-restricting-copies"> - <title>Restricting Multiple Copies</title> - - <para>The LPD system makes it easy for users to print multiple copies - of a file. Users can print jobs with <command>lpr -#5</command> - (for example) and get five copies of each file in the job. Whether - this is a good thing is up to you.</para> - - <para>If you feel multiple copies cause unnecessary wear and tear on - your printers, you can disable the <option>-#</option> option to - &man.lpr.1; by adding the <literal>sc</literal> capability to the - <filename>/etc/printcap</filename> file. When users submit jobs - with the <option>-#</option> option, they will see:</para> - - <screen>lpr: multiple copies are not allowed</screen> - - - <para>Note that if you have set up access to a printer remotely (see - section <link linkend="printing-advanced-network-rm">Printers - Installed on Remote Hosts</link>), you need the - <literal>sc</literal> capability on the remote - <filename>/etc/printcap</filename> files as well, or else users will - still be able to submit multiple-copy jobs by using another - host.</para> - - <para>Here is an example. This is the - <filename>/etc/printcap</filename> file for the host - <hostid>rose</hostid>. The printer <literal>rattan</literal> is - quite hearty, so we will allow multiple copies, but the laser - printer <literal>bamboo</literal>'s a bit more delicate, so we will - disable multiple copies by adding the <literal>sc</literal> - capability:</para> - - <programlisting> -# -# /etc/printcap for host rose - restrict multiple copies on bamboo -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:sc:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>Now, we also need to add the <literal>sc</literal> capability on - the host <hostid>orchid</hostid>'s - <filename>/etc/printcap</filename> (and while we are at it, let us - disable multiple copies for the printer - <literal>teak</literal>):</para> - - <programlisting> -# -# /etc/printcap for host orchid - no multiple copies for local -# printer teak or remote printer bamboo -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\ - :if=/usr/local/libexec/ifhp:\ - :vf=/usr/local/libexec/vfhp:\ - :of=/usr/local/libexec/ofhp: - -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc:</programlisting> - - <para>By using the <literal>sc</literal> capability, we prevent the - use of <command>lpr -#</command>, but that still does not prevent - users from running &man.lpr.1; - multiple times, or from submitting the same file multiple times in - one job like this:</para> - - <screen>&prompt.user; <userinput>lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign</userinput></screen> - - <para>There are many ways to prevent this abuse (including ignoring - it) which you are free to explore.</para> - </sect3> - - <sect3 id="printing-advanced-restricting-access"> - <title>Restricting Access To Printers</title> - - <para>You can control who can print to what printers by using the UNIX - group mechanism and the <literal>rg</literal> capability in - <filename>/etc/printcap</filename>. Just place the users you want - to have access to a printer in a certain group, and then name that - group in the <literal>rg</literal> capability.</para> - - <para>Users outside the group (including root) will be greeted with - - <errorname>lpr: Not a member of the restricted group</errorname> - - if they try to print to the controlled printer.</para> - - <para>As with the <literal>sc</literal> (suppress multiple copies) - capability, you need to specify <literal>rg</literal> on remote - hosts that also have access to your printers, if you feel it is - appropriate (see section <link - linkend="printing-advanced-network-rm">Printers Installed on - Remote Hosts</link>).</para> - - <para>For example, we will let anyone access the printer - <literal>rattan</literal>, but only those in group - <literal>artists</literal> can use <literal>bamboo</literal>. Here - is the familiar <filename>/etc/printcap</filename> for host - <hostid>rose</hostid>:</para> - - <programlisting> -# -# /etc/printcap for host rose - restricted group for bamboo -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>Let us leave the other example - <filename>/etc/printcap</filename> file (for the host - <hostid>orchid</hostid>) alone. Of course, anyone on - <hostid>orchid</hostid> can print to <literal>bamboo</literal>. It - might be the case that we only allow certain logins on - <hostid>orchid</hostid> anyway, and want them to have access to the - printer. Or not.</para> - - <note> - <para>There can be only one restricted group per printer.</para> - </note> - </sect3> - - <sect3 id="printing-advanced-restricting-sizes"> - <title>Controlling Sizes of Jobs Submitted</title> - - <para>If you have many users accessing the printers, you probably need - to put an upper limit on the sizes of the files users can submit to - print. After all, there is only so much free space on the - filesystem that houses the spooling directories, and you also need - to make sure there is room for the jobs of other users.</para> - - <para>LPD enables you to limit the maximum byte size a file in a job - can be with the <literal>mx</literal> capability. The units are in - BUFSIZ blocks, which are 1024 bytes. If you put a zero for this - capability, there will be no limit on file size; however, if no - <literal>mx</literal> capability is specified, then a default limit - of 1000 blocks will be used.</para> - - <note> - <para>The limit applies to <emphasis>files</emphasis> in a job, and - <emphasis>not</emphasis> the total job size.</para> - </note> - - <para>LPD will not refuse a file that is larger than the limit you - place on a printer. Instead, it will queue as much of the file up - to the limit, which will then get printed. The rest will be - discarded. Whether this is correct behavior is up for - debate.</para> - - <para>Let us add limits to our example printers - <literal>rattan</literal> and <literal>bamboo</literal>. Since - those artists' PostScript files tend to be large, we will limit them - to five megabytes. We will put no limit on the plain text line - printer:</para> - - <programlisting> -# -# /etc/printcap for host rose -# - -# -# No limit on job size: -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:mx#0:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -# -# Limit of five megabytes: -# -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>Again, the limits apply to the local users only. If you have - set up access to your printers remotely, remote users will not get - those limits. You will need to specify the <literal>mx</literal> - capability in the remote <filename>/etc/printcap</filename> files as - well. See section <link - linkend="printing-advanced-network-rm">Printers Installed on - Remote Hosts</link> for more information on remote - printing.</para> - - <para>There is another specialized way to limit job sizes from remote - printers; see section <link - linkend="printing-advanced-restricting-remote">Restricting Jobs - from Remote Printers</link>.</para> - </sect3> - - <sect3 id="printing-advanced-restricting-remote"> - <title>Restricting Jobs from Remote Printers</title> - - <para>The LPD spooling system provides several ways to restrict print - jobs submitted from remote hosts:</para> - - <variablelist> - <varlistentry> - <term>Host restrictions</term> - - <listitem> - <para>You can control from which remote hosts a local LPD - accepts requests with the files - <filename>/etc/hosts.equiv</filename> and - <filename>/etc/hosts.lpd</filename>. LPD checks to see if an - incoming request is from a host listed in either one of these - files. If not, LPD refuses the request.</para> - - <para>The format of these files is simple: one host name per - line. Note that the file - <filename>/etc/hosts.equiv</filename> is also used by the - &man.ruserok.3; protocol, and affects programs like - &man.rsh.1; and &man.rcp.1;, so be careful.</para> - - <para>For example, here is the - <filename>/etc/hosts.lpd</filename> file on the host - <hostid>rose</hostid>:</para> - - <programlisting> -orchid -violet -madrigal.fishbaum.de</programlisting> - - <para>This means <hostid>rose</hostid> will accept requests from - the hosts <hostid>orchid</hostid>, <hostid>violet</hostid>, - and <hostid role="fqdn">madrigal.fishbaum.de</hostid>. If any - other host tries to access <hostid>rose</hostid>'s LPD, LPD - will refuse them.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Size restrictions</term> - - <listitem> - <para>You can control how much free space there needs to remain - on the filesystem where a spooling directory resides. Make a - file called <filename>minfree</filename> in the spooling - directory for the local printer. Insert in that file a number - representing how many disk blocks (512 bytes) of free space - there has to be for a remote job to be accepted.</para> - - <para>This lets you insure that remote users will not fill your - filesystem. You can also use it to give a certain priority to - local users: they will be able to queue jobs long after the - free disk space has fallen below the amount specified in the - <filename>minfree</filename> file.</para> - - <para>For example, let us add a <filename>minfree</filename> - file for the printer <hostid>bamboo</hostid>. We examine - <filename>/etc/printcap</filename> to find the spooling - directory for this printer; here is <hostid>bamboo</hostid>'s - entry:</para> - - <programlisting> -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:mx#5000:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>The spooling directory is the given in the - <literal>sd</literal> capability. We will make three - megabytes (which is 6144 disk blocks) the amount of free disk - space that must exist on the filesystem for LPD to accept - remote jobs:</para> - - <screen>&prompt.root; <userinput>echo 6144 > /var/spool/lpd/bamboo/minfree</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term>User restrictions</term> - - <listitem> - <para>You can control which remote users can print to local - printers by specifying the <literal>rs</literal> capability in - <filename>/etc/printcap</filename>. When - <literal>rs</literal> appears in the entry for a - locally-attached printer, LPD will accept jobs from remote - hosts <emphasis>if</emphasis> the user submitting the job also - has an account of the same login name on the local host. - Otherwise, LPD refuses the job.</para> - - <para>This capability is particularly useful in an environment - where there are (for example) different departments sharing a - network, and some users transcend departmental boundaries. By - giving them accounts on your systems, they can use your - printers from their own departmental systems. If you would - rather allow them to use <emphasis>only</emphasis> your - printers and not your compute resources, you can give them - “token” accounts, with no home directory and a - useless shell like <filename>/usr/bin/false</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - </sect2> - - <sect2 id="printing-advanced-acct"> - <title>Accounting for Printer Usage</title> - - <para>So, you need to charge for printouts. And why not? Paper and ink - cost money. And then there are maintenance costs—printers are - loaded with moving parts and tend to break down. You have examined - your printers, usage patterns, and maintenance fees and have come up - with a per-page (or per-foot, per-meter, or per-whatever) cost. Now, - how do you actually start accounting for printouts?</para> - - <para>Well, the bad news is the LPD spooling system does not provide - much help in this department. Accounting is highly dependent on the - kind of printer in use, the formats being printed, and - <emphasis>your</emphasis> requirements in charging for printer - usage.</para> - - <para>To implement accounting, you have to modify a printer's text - filter (to charge for plain text jobs) and the conversion filters (to - charge for other file formats), to count pages or query the printer - for pages printed. You cannot get away with using the simple output - filter, since it cannot do accounting. See section <link - linkend="printing-advanced-filter-intro">Filters</link>.</para> - - <para>Generally, there are two ways to do accounting:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Periodic accounting</emphasis> is the more common - way, possibly because it is easier. Whenever someone prints a - job, the filter logs the user, host, and number of pages to an - accounting file. Every month, semester, year, or whatever time - period you prefer, you collect the accounting files for the - various printers, tally up the pages printed by users, and charge - for usage. Then you truncate all the logging files, starting with - a clean slate for the next period.</para> - </listitem> - - <listitem> - <para><emphasis>Timely accounting</emphasis> is less common, - probably because it is more difficult. This method has the - filters charge users for printouts as soon as they use the - printers. Like disk quotas, the accounting is immediate. You can - prevent users from printing when their account goes in the red, - and might provide a way for users to check and adjust their - “print quotas.” But this method requires some database - code to track users and their quotas.</para> - </listitem> - </itemizedlist> - - <para>The LPD spooling system supports both methods easily: since you - have to provide the filters (well, most of the time), you also have to - provide the accounting code. But there is a bright side: you have - enormous flexibility in your accounting methods. For example, you - choose whether to use periodic or timely accounting. You choose what - information to log: user names, host names, job types, pages printed, - square footage of paper used, how long the job took to print, and so - forth. And you do so by modifying the filters to save this - information.</para> - - <sect3> - <title>Quick and Dirty Printer Accounting</title> - - <para>FreeBSD comes with two programs that can get you set up with - simple periodic accounting right away. They are the text filter - <command>lpf</command>, described in section <link - linkend="printing-advanced-lpf">lpf: a Text Filter</link>, and - &man.pac.8;, a program to gather and total - entries from printer accounting files.</para> - - <para>As mentioned in the section on filters (<link - linkend="printing-advanced-filters">Filters</link>), LPD starts - the text and the conversion filters with the name of the accounting - file to use on the filter command line. The filters can use this - argument to know where to write an accounting file entry. The name - of this file comes from the <literal>af</literal> capability in - <filename>/etc/printcap</filename>, and if not specified as an - absolute path, is relative to the spooling directory.</para> - - <para>LPD starts <command>lpf</command> with page width and length - arguments (from the <literal>pw</literal> and <literal>pl</literal> - capabilities). <command>lpf</command> uses these arguments to - determine how much paper will be used. After sending the file to - the printer, it then writes an accounting entry in the accounting - file. The entries look like this:</para> - - <programlisting> -2.00 rose:andy -3.00 rose:kelly -3.00 orchid:mary -5.00 orchid:mary -2.00 orchid:zhang</programlisting> - - <para>You should use a separate accounting file for each printer, as - <command>lpf</command> has no file locking logic built into it, and - two <command>lpf</command>s might corrupt each other's entries if - they were to write to the same file at the same time. A easy way to - insure a separate accounting file for each printer is to use - <literal>af=acct</literal> in <filename>/etc/printcap</filename>. - Then, each accounting file will be in the spooling directory for a - printer, in a file named <filename>acct</filename>.</para> - - <para>When you are ready to charge users for printouts, run the - &man.pac.8; program. Just change to the spooling directory for - the printer you want to collect on and type <literal>pac</literal>. - You will get a dollar-centric summary like the following:</para> - - <screen> Login pages/feet runs price -orchid:kelly 5.00 1 $ 0.10 -orchid:mary 31.00 3 $ 0.62 -orchid:zhang 9.00 1 $ 0.18 -rose:andy 2.00 1 $ 0.04 -rose:kelly 177.00 104 $ 3.54 -rose:mary 87.00 32 $ 1.74 -rose:root 26.00 12 $ 0.52 - -total 337.00 154 $ 6.74</screen> - - <para>These are the arguments &man.pac.8; expects:</para> - - <variablelist> - <varlistentry> - <term><option>-P<replaceable>printer</replaceable></option></term> - - <listitem> - <para>Which <replaceable>printer</replaceable> to summarize. - This option works only if there is an absolute path in the - <literal>af</literal> capability in - <filename>/etc/printcap</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>Sort the output by cost instead of alphabetically by user - name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-m</option></term> - - <listitem> - <para>Ignore host name in the accounting files. With this - option, user <username>smith</username> on host - <hostid>alpha</hostid> is the same user - <username>smith</username> on host <hostid>gamma</hostid>. - Without, they are different users.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p<replaceable>price</replaceable></option></term> - - <listitem> - <para>Compute charges with <replaceable>price</replaceable> - dollars per page or per foot instead of the price from the - <literal>pc</literal> capability in - <filename>/etc/printcap</filename>, or two cents (the - default). You can specify <replaceable>price</replaceable> as - a floating point number.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - - <listitem> - <para>Reverse the sort order.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - - <listitem> - <para>Make an accounting summary file and truncate the - accounting file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>name</replaceable> - <replaceable>…</replaceable></term> - - <listitem> - <para>Print accounting information for the given user - <replaceable>names</replaceable> only.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In the default summary that &man.pac.8; produces, you see the - number of pages printed by each user from various hosts. If, at - your site, host does not matter (because users can use any host), - run <command>pac -m</command>, to produce the following - summary:</para> - - <screen> Login pages/feet runs price -andy 2.00 1 $ 0.04 -kelly 182.00 105 $ 3.64 -mary 118.00 35 $ 2.36 -root 26.00 12 $ 0.52 -zhang 9.00 1 $ 0.18 - -total 337.00 154 $ 6.74</screen> - - - <para>To compute the dollar amount due, - &man.pac.8; uses the <literal>pc</literal> capability in the - <filename>/etc/printcap</filename> file (default of 200, or 2 cents - per page). Specify, in hundredths of cents, the price per page or - per foot you want to charge for printouts in this capability. You - can override this value when you run &man.pac.8; with the - <option>-p</option> option. The units for the <option>-p</option> - option are in dollars, though, not hundredths of cents. For - example, - - <screen>&prompt.root; <userinput>pac -p1.50</userinput></screen> - - makes each page cost one dollar and fifty cents. You can really - rake in the profits by using this option.</para> - - <para>Finally, running <command>pac -s</command> will save the summary - information in a summary accounting file, which is named the same as - the printer's accounting file, but with <literal>_sum</literal> - appended to the name. It then truncates the accounting file. When - you run &man.pac.8; again, it rereads the - summary file to get starting totals, then adds information from the - regular accounting file.</para> - </sect3> - - <sect3> - <title>How Can You Count Pages Printed?</title> - - <para>In order to perform even remotely accurate accounting, you need - to be able to determine how much paper a job uses. This is the - essential problem of printer accounting.</para> - - <para>For plain text jobs, the problem's not that hard to solve: you - count how many lines are in a job and compare it to how many lines - per page your printer supports. Do not forget to take into account - backspaces in the file which overprint lines, or long logical lines - that wrap onto one or more additional physical lines.</para> - - <para>The text filter <command>lpf</command> (introduced in <link - linkend="printing-advanced-lpf">lpf: a Text Filter</link>) takes - into account these things when it does accounting. If you are - writing a text filter which needs to do accounting, you might want - to examine <command>lpf</command>'s source code.</para> - - <para>How do you handle other file formats, though?</para> - - <para>Well, for DVI-to-LaserJet or DVI-to-PostScript conversion, you - can have your filter parse the diagnostic output of - <command>dvilj</command> or <command>dvips</command> and look to see - how many pages were converted. You might be able to do similar - things with other file formats and conversion programs.</para> - - <para>But these methods suffer from the fact that the printer may not - actually print all those pages. For example, it could jam, run out - of toner, or explode—and the user would still get - charged.</para> - - <para>So, what can you do?</para> - - <para>There is only one <emphasis>sure</emphasis> way to do - <emphasis>accurate</emphasis> accounting. Get a printer that can - tell you how much paper it uses, and attach it via a serial line or - a network connection. Nearly all PostScript printers support this - notion. Other makes and models do as well (networked Imagen laser - printers, for example). Modify the filters for these printers to - get the page usage after they print each job and have them log - accounting information based on that value - <emphasis>only</emphasis>. There is no line counting nor - error-prone file examination required.</para> - - <para>Of course, you can always be generous and make all printouts - free.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="printing-lpd-alternatives"> - <title>Alternatives to the Standard Spooler</title> - - <para>If you have been reading straight through this manual, by now you - have learned just about everything there is to know about the LPD - spooling system that comes with FreeBSD. You can probably appreciate - many of its shortcomings, which naturally leads to the question: - “What other spooling systems are out there (and work with - FreeBSD)?”</para> - - <para>Unfortunately, I have located only <emphasis>two</emphasis> - alternatives—and they are almost identical to each other! They - are:</para> - - <variablelist> - <varlistentry> - <term>PLP, the Portable Line Printer Spooler System</term> - - <listitem> - <para>PLP was based on software developed by Patrick Powell and then - maintained by an Internet-wide group of developers. The main site - for the software is at <ulink - URL="ftp://ftp.iona.ie/pub/plp">ftp://ftp.iona.ie/pub/plp</ulink>. - There is also a <ulink - URL="http://www.iona.ie:8000/www/hyplan/jmason/plp.html">web - page</ulink>.</para> - - <para>It is quite similar to the BSD LPD spooler, but boasts a - host of features, including:</para> - - <itemizedlist> - <listitem> - <para>Better network support, including built-in support for - networked printers, NIS-maintained printcaps, and NFS-mounted - spooling directories</para> - </listitem> - - <listitem> - <para>Sophisticated queue management, allowing multiple printers - on a queue, transfer of jobs between queues, and queue - redirection</para> - </listitem> - - <listitem> - <para>Remote printer control functions</para> - </listitem> - - <listitem> - <para>Prioritization of jobs</para> - </listitem> - - <listitem> - <para>Expansive security and access options</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>LPRng</term> - - <listitem> - <para>LPRng, which purportedly means “LPR: the Next - Generation” is a complete rewrite of PLP. Patrick Powell - and Justin Mason (the principal maintainer of PLP) collaborated to - make LPRng. The main site for LPRng is <ulink - URL="ftp://dickory.sdsu.edu/pub/LPRng">ftp://dickory.sdsu.edu/pub/LPRng</ulink>.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1> - <title>Acknowledgments</title> - - <para>I would like to thank the following people who have assisted in the - development of this document:</para> - - <variablelist> - <varlistentry> - <term>Daniel Eischen - <email>deischen@iworks.interworks.org</email></term> - - <listitem> - <para>For providing a plethora of HP filter programs for - perusal.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.jehamby;</term> - - <listitem> - <para>For the Ghostscript-to-HP filter.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.jfieber;</term> - - <listitem> - <para> For debugging why printing from Windows 95 to a FreeBSD - system simulating a PostScript printer with Ghostscript didn't - produce correct output, and suggesting a fix, which is included - herein.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Stephen Montgomery-Smith - <email>stephen@math.missouri.edu</email></term> - - <listitem> - <para>For suggesting using "\033&l0H" instead of "\f" to eject - the last page on HP printers; the latter could eject an extra - blank page while the former never does.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>My wife, Mary Kelly - <email>urquhart@argyre.colorado.edu</email></term> - - <listitem> - <para>For allowing me to spend more time with FreeBSD than - with her.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - - diff --git a/en/handbook/quotas/chapter.sgml b/en/handbook/quotas/chapter.sgml deleted file mode 100644 index 680cb5fce0..0000000000 --- a/en/handbook/quotas/chapter.sgml +++ /dev/null @@ -1,232 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.9 1999-06-15 20:24:54 mpp Exp $ ---> - -<chapter id="quotas"> - <title>Disk Quotas</title> - - <para><emphasis>Contributed by &a.mpp;. 26 February - 1996</emphasis></para> - - <para>Quotas are an optional feature of the operating system that allow you - to limit the amount of disk space and/or the number of files a user, or - members of a group, may allocate on a per-file system basis. This is used - most often on timesharing systems where it is desirable to limit the - amount of resources any one user or group of users may allocate. This - will prevent one user from consuming all of the available disk - space.</para> - - <sect1> - <title>Configuring Your System to Enable Disk Quotas</title> - - <para>Before attempting to use disk quotas it is necessary to make sure - that quotas are configured in your kernel. This is done by adding the - following line to your kernel configuration file:</para> - - <programlisting> -options QUOTA</programlisting> - - <para>The stock <filename>GENERIC</filename> kernel does not have this - enabled by default, so you will have to configure, build and install a - custom kernel in order to use disk quotas. Please refer to the <link - linkend="kernelconfig">Configuring the FreeBSD Kernel</link> section - for more information on kernel configuration.</para> - - <para>Next you will need to enable disk quotas in - <filename>/etc/sysconfig</filename>. This is done by changing the line: - - <programlisting> -quotas=NO</programlisting> - - to: - - <programlisting> -quotas=YES</programlisting></para> - - <para>If you are running FreeBSD 2.2.2 or later, the configuration file - will be <filename>/etc/rc.conf</filename> instead and the variable name - changed to:</para> - - <programlisting> -check_quotas=YES</programlisting> - - <para>Finally you will need to edit <filename>/etc/fstab</filename> to - enable disk quotas on a per-file system basis. This is where you can - either enable user or group quotas or both for all of your file - systems.</para> - - <para>To enable per-user quotas on a file system, add the - <literal>userquota</literal> option to the options field in the - <filename>/etc/fstab</filename> entry for the file system you want to to - enable quotas on. For example:</para> - - <programlisting> -/dev/da1s2g /home ufs rw,userquota 1 2</programlisting> - - <para>Similarly, to enable group quotas, use the - <literal>groupquota</literal> option instead of the - <literal>userquota</literal> keyword. To enable both user and group - quotas, change the entry as follows:</para> - - <programlisting> -/dev/da1s2g /home ufs rw,userquota,groupquota 1 2</programlisting> - - <para>By default the quota files are stored in the root directory of the - file system with the names <filename>quota.user</filename> and - <filename>quota.group</filename> for user and group quotas respectively. - See <command>man fstab</command> for more information. Even though that - man page says that you can specify an alternate location for the quota - files, this is not recommended since all of the various quota utilities - do not seem to handle this properly.</para> - - <para>At this point you should reboot your system with your new kernel. - <filename>/etc/rc</filename> will automatically run the appropriate - commands to create the initial quota files for all of the quotas you - enabled in <filename>/etc/fstab</filename>, so there is no need to - manually create any zero length quota files.</para> - - <para>In the normal course of operations you should not be required to run - the <command>quotacheck</command>, <command>quotaon</command>, or - <command>quotaoff</command> commands manually. However, you may want to - read their man pages just to be familiar with their operation.</para> - </sect1> - - <sect1> - <title>Setting Quota Limits</title> - - <para>Once you have configured your system to enable quotas, verify that - they really are enabled. An easy way to do this is to run</para> - - <screen>&prompt.root; <userinput>quota -v</userinput></screen> - - <para>You should see a one line summary of disk usage and current quota - limits for each file system that quotas are enabled on.</para> - - <para>You are now ready to start assigning quota limits with the - <command>edquota</command> command.</para> - - <para>You have several options on how to enforce limits on the amount of - disk space a user or group may allocate, and how many files they may - create. You may limit allocations based on disk space (block quotas) or - number of files (inode quotas) or a combination of both. Each of these - limits are further broken down into two categories: hard and soft - limits.</para> - - <para>A hard limit may not be exceeded. Once a user reaches their hard - limit they may not make any further allocations on the file system in - question. For example, if the user has a hard limit of 500 blocks on a - file system and is currently using 490 blocks, the user can only - allocate an additional 10 blocks. Attempting to allocate an additional - 11 blocks will fail.</para> - - <para>Soft limits on the other hand can be exceeded for a limited amount - of time. This period of time is known as the grace period, which is one - week by default. If a user stays over his or her soft limit longer than - their grace period, the soft limit will turn into a hard limit and no - further allocations will be allowed. When the user drops back below the - soft limit, the grace period will be reset.</para> - - <para>The following is an example of what you might see when you run - then <command>edquota</command> command. When the - <command>edquota</command> command is invoked, you are placed into the - editor specified by the <envar>EDITOR</envar> environment variable, or - in the <command>vi</command> editor if the <envar>EDITOR</envar> - variable is not set, to allow you to edit the quota limits.</para> - - <screen>&prompt.root; <userinput>edquota -u test</userinput></screen> - - <programlisting> -Quotas for user test: -/usr: blocks in use: 65, limits (soft = 50, hard = 75) - inodes in use: 7, limits (soft = 50, hard = 60) -/usr/var: blocks in use: 0, limits (soft = 50, hard = 75) - inodes in use: 0, limits (soft = 50, hard = 60)</programlisting> - - <para>You will normally see two lines for each file system that has quotas - enabled. One line for the block limits, and one line for inode limits. - Simply change the value you want updated to modify the quota limit. For - example, to raise this users block limit from a soft limit of 50 and a - hard limit of 75 to a soft limit of 500 and a hard limit of 600, change: - <programlisting> /usr: blocks in use: 65, limits (soft = 50, hard = - 75)</programlisting> to: <programlisting> /usr: blocks in use: 65, - limits (soft = 500, hard = 600)</programlisting></para> - - <para>The new quota limits will be in place when you exit the - editor.</para> - - <para>Sometimes it is desirable to set quota limits on a range of uids. - This can be done by use of the <option>-p</option> option on the - <command>edquota</command> command. First, assign the desired quota - limit to a user, and then run <command>edquota -p protouser - startuid-enduid</command>. For example, if user - <username>test</username> has the desired quota limits, the following - command can be used to duplicate those quota limits for uids 10,000 - through 19,999:</para> - - <screen>&prompt.root; <userinput>edquota -p test 10000-19999</userinput></screen> - - <para>The ability to specify uid ranges was added to the system after 2.1 - was released. If you need this feature on a 2.1 system, you will need - to obtain a newer copy of edquota.</para> - - <para>See <command>man edquota</command> for more detailed - information.</para> - </sect1> - - <sect1> - <title>Checking Quota Limits and Disk Usage</title> - - <para>You can use either the <command>quota</command> or the - <command>repquota</command> commands to check quota limits and disk - usage. The <command>quota</command> command can be used to check - individual user and group quotas and disk usage. Only the super-user - may examine quotas and usage for other users, or for groups that they - are not a member of. The <command>repquota</command> command can be - used to get a summary of all quotas and disk usage for file systems with - quotas enabled.</para> - - <para>The following is some sample output from the <command>quota - -v</command> command for a user that has quota limits on two file - systems.</para> - - - <programlisting> -Disk quotas for user test (uid 1002): - Filesystem blocks quota limit grace files quota limit grace - /usr 65* 50 75 5days 7 50 60 - /usr/var 0 50 75 0 50 60</programlisting> - - <para>On the <filename>/usr</filename> file system in the above example - this user is currently 15 blocks over their soft limit of 50 blocks and - has 5 days of their grace period left. Note the asterisk - <literal>*</literal> which indicates that the user is currently over - their quota limit.</para> - - <para>Normally file systems that the user is not using any disk space on - will not show up in the output from the <command>quota</command> - command, even if they have a quota limit assigned for that file system. - The <option>-v</option> option will display those file systems, such as - the <filename>/usr/var</filename> file system in the above - example.</para> - </sect1> - - <sect1> - <title>* Quotas over NFS</title> - - <para>This section is still under development.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/security/chapter.sgml b/en/handbook/security/chapter.sgml deleted file mode 100644 index 98e355eea3..0000000000 --- a/en/handbook/security/chapter.sgml +++ /dev/null @@ -1,1612 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.17 1999-08-05 20:48:23 nik Exp $ ---> - -<chapter id="security"> - <title>Security</title> - - <sect1 id="crypt"> - <title>DES, MD5, and Crypt</title> - - <para><emphasis>Contributed by &a.wollman; 24 September - 1995.</emphasis></para> - - <para>In order to protect the security of passwords on UN*X systems from - being easily exposed, passwords have traditionally been scrambled in - some way. Starting with Bell Labs' Seventh Edition Unix, passwords were - encrypted using what the security people call a “one-way hash - function”. That is to say, the password is transformed in such a - way that the original password cannot be regained except by brute-force - searching the space of possible passwords. Unfortunately, the only - secure method that was available to the AT&T researchers at the time - was based on DES, the Data Encryption Standard. This causes only - minimal difficulty for commercial vendors, but is a serious problem for - an operating system like FreeBSD where all the source code is freely - available, because national governments in many places like to place - restrictions on cross-border transport of DES and other encryption - software.</para> - - <para>So, the FreeBSD team was faced with a dilemma: how could we provide - compatibility with all those UNIX systems out there while still not - running afoul of the law? We decided to take a dual-track approach: we - would make distributions which contained only a non-regulated password - scrambler, and then provide as a separate add-on library the DES-based - password hash. The password-scrambling function was moved out of the C - library to a separate library, called <filename>libcrypt</filename> - because the name of the C function to implement it is - <function>crypt</function>. In FreeBSD 1.x and some pre-release 2.0 - snapshots, the non-regulated scrambler uses an insecure function written - by Nate Williams; in subsequent releases this was replaced by a - mechanism using the RSA Data Security, Inc., MD5 one-way hash function. - Because neither of these functions involve encryption, they are believed - to be exportable from the US and importable into many other - countries.</para> - - <para>Meanwhile, work was also underway on the DES-based password hash - function. First, a version of the <function>crypt</function> function - which was written outside the US was imported, thus synchronizing the US - and non-US code. Then, the library was modified and split into two; the - DES <filename>libcrypt</filename> contains only the code involved in - performing the one-way password hash, and a separate - <filename>libcipher</filename> was created with the entry points to - actually perform encryption. The code was partitioned in this way to - make it easier to get an export license for the compiled library.</para> - - <sect2> - <title>Recognizing your <command>crypt</command> mechanism</title> - - <para>It is fairly easy to recognize whether a particular password - string was created using the DES- or MD5-based hash function. MD5 - password strings always begin with the characters - <literal>$1$</literal>. DES password strings do not have any - particular identifying characteristics, but they are shorter than MD5 - passwords, and are coded in a 64-character alphabet which does not - include the <literal>$</literal> character, so a relatively short - string which doesn't begin with a dollar sign is very likely a DES - password.</para> - - <para>Determining which library is being used on your system is fairly - easy for most programs, except for those like <command>init</command> - which are statically linked. (For those programs, the only way is to - try them on a known password and see if it works.) Programs which use - <function>crypt</function> are linked against - <filename>libcrypt</filename>, which for each type of library is a - symbolic link to the appropriate implementation. For example, on a - system using the DES versions:</para> - - <screen>&prompt.user; <userinput>ls -l /usr/lib/libcrypt*</userinput> -lrwxr-xr-x 1 root wheel 13 Mar 19 06:56 libcrypt.a -> libdescrypt.a -lrwxr-xr-x 1 root wheel 18 Mar 19 06:56 libcrypt.so.2.0 -> libdescrypt.so.2.0 -lrwxr-xr-x 1 root wheel 15 Mar 19 06:56 libcrypt_p.a -> libdescrypt_p.a</screen> - - <para>On a system using the MD5-based libraries, the same links will be - present, but the target will be <filename>libscrypt</filename> rather - than <filename>libdescrypt</filename>.</para> - </sect2> - </sect1> - - <sect1 id="skey"> - <!-- - Copyright 1995 Massachusetts Institute of Technology - - Permission to use, copy, modify, and distribute this software and - its documentation for any purpose and without fee is hereby - granted, provided that both the above copyright notice and this - permission notice appear in all copies, that both the above - copyright notice and this permission notice appear in all - supporting documentation, and that the name of M.I.T. not be used - in advertising or publicity pertaining to distribution of the - software without specific, written prior permission. M.I.T. makes - no representations about the suitability of this software for any - purpose. It is provided "as is" without express or implied - warranty. - - THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS - ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, - INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT - SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT - OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - --> - - <title>S/Key</title> - - <para><emphasis>Contributed by &a.wollman; 25 September - 1995.</emphasis></para> - - <para>S/Key is a one-time password scheme based on a one-way hash function - (in our version, this is MD4 for compatibility; other versions have used - MD5 and DES-MAC). S/Key has been a standard part of all FreeBSD - distributions since version 1.1.5, and is also implemented on a large - and growing number of other systems. S/Key is a registered trademark of - Bell Communications Research, Inc.</para> - - <para>There are three different sorts of passwords which we will talk - about in the discussion below. The first is your usual UNIX-style or - Kerberos password; we will call this a “UNIX password”. The - second sort is the one-time password which is generated by the S/Key - <command>key</command> program and accepted by the - <command>keyinit</command> program and the login prompt; we will call - this a “one-time password”. The final sort of password is - the secret password which you give to the <command>key</command> program - (and sometimes the <command>keyinit</command> program) which it uses to - generate one-time passwords; we will call it a “secret - password” or just unqualified “password”.</para> - - <para>The secret password does not necessarily have anything to do with - your UNIX password (while they can be the same, this is not - recommended). While UNIX passwords are limited to eight characters in - length, your S/Key secret password can be as long as you like; I use - seven-word phrases. In general, the S/Key system operates completely - independently of the UNIX password system.</para> - - <para>There are in addition two other sorts of data involved in the S/Key - system; one is called the “seed” or (confusingly) - “key”, and consists of two letters and five digits, and the - other is the “iteration count” and is a number between 100 - and 1. S/Key constructs a one-time password from these components by - concatenating the seed and the secret password, then applying a one-way - hash (the RSA Data Security, Inc., MD4 secure hash function) - iteration-count times, and turning the result into six short English - words. The <command>login</command> and <command>su</command> programs - keep track of the last one-time password used, and the user is - authenticated if the hash of the user-provided password is equal to the - previous password. Because a one-way hash function is used, it is not - possible to generate future one-time passwords having overheard one - which was successfully used; the iteration count is decremented after - each successful login to keep the user and login program in sync. (When - you get the iteration count down to 1, it is time to reinitialize - S/Key.)</para> - - <para>There are four programs involved in the S/Key system which we will - discuss below. The <command>key</command> program accepts an iteration - count, a seed, and a secret password, and generates a one-time password. - The <command>keyinit</command> program is used to initialized S/Key, and - to change passwords, iteration counts, or seeds; it takes either a - secret password, or an iteration count, seed, and one-time password. - The <command>keyinfo</command> program examines the - <filename>/etc/skeykeys</filename> file and prints out the invoking - user's current iteration count and seed. Finally, the - <command>login</command> and <command>su</command> programs contain the - necessary logic to accept S/Key one-time passwords for authentication. - The <command>login</command> program is also capable of disallowing the - use of UNIX passwords on connections coming from specified - addresses.</para> - - <para>There are four different sorts of operations we will cover. The - first is using the <command>keyinit</command> program over a secure - connection to set up S/Key for the first time, or to change your - password or seed. The second operation is using the - <command>keyinit</command> program over an insecure connection, in - conjunction with the <command>key</command> program over a secure - connection, to do the same. The third is using the - <command>key</command> program to log in over an insecure connection. - The fourth is using the <command>key</command> program to generate a - number of keys which can be written down or printed out to carry with - you when going to some location without secure connections to anywhere - (like at a conference).</para> - - <sect2> - <title>Secure connection initialization</title> - - <para>To initialize S/Key, change your password, or change your seed - while logged in over a secure connection (e.g., on the console of a - machine), use the <command>keyinit</command> command without any - parameters while logged in as yourself:</para> - - <screen>&prompt.user; keyinit -Updating wollman: ) these will not appear if you -Old key: ha73895 ) have not used S/Key before -Reminder - Only use this method if you are directly connected. -If you are using telnet or rlogin exit with no password and use keyinit -s. -<prompt>Enter secret password:</prompt> ) I typed my pass phrase here -<prompt>Again secret password:</prompt> ) I typed it again ID - -wollman s/key is 99 ha73896 ) discussed below SAG -HAS FONT GOUT FATE BOOM )</screen> - - <para>There is a lot of information here. At the<prompt>Enter secret - password:</prompt> prompt, you should enter some password or phrase - (I use phrases of minimum seven words) which will be needed to - generate login keys. The line starting `ID' gives the parameters of - your particular S/Key instance: your login name, the iteration count, - and seed. When logging in with S/Key, the system will remember these - parameters and present them back to you so you do not have to remember - them. The last line gives the particular one-time password which - corresponds to those parameters and your secret password; if you were - to re-login immediately, this one-time password is the one you would - use.</para> - </sect2> - - <sect2> - <title>Insecure connection initialization</title> - - <para>To initialize S/Key or change your password or seed over an - insecure connection, you will need to already have a secure connection - to some place where you can run the <command>key</command> program; - this might be in the form of a desk accessory on a Macintosh, or a - shell prompt on a machine you trust (we will show the latter). You - will also need to make up an iteration count (100 is probably a good - value), and you may make up your own seed or use a randomly-generated - one. Over on the insecure connection (to the machine you are - initializing), use the <command>keyinit -s</command> command:</para> - - <screen>&prompt.user; <userinput>keyinit -s</userinput> -Updating wollman: Old key: kh94741 -Reminder you need the 6 English words from the skey command. -<prompt>Enter sequence count from 1 to 9999:</prompt> <userinput>100</userinput> ) I typed this -<prompt>Enter new key [default kh94742]:</prompt> -s/key 100 kh94742</screen> - - <para>To accept the default seed (which the <command>keyinit</command> - program confusingly calls a <literal>key</literal>), press return. - Then move over to your secure connection or S/Key desk accessory, and - give it the same parameters:</para> - - <screen>&prompt.user; <userinput>key 100 kh94742</userinput> -Reminder - Do not use this program while logged in via telnet or rlogin. -<prompt>Enter secret password:</prompt> ) I typed my secret password -HULL NAY YANG TREE TOUT VETO</screen> - - <para>Now switch back over to the insecure connection, and copy the - one-time password generated by <command>key</command> over to the - <command>keyinit</command> program:</para> - - <screen><prompt>s/key access password:</prompt> <userinput>HULL NAY YANG TREE TOUT VETO</userinput> -ID wollman s/key is 100 kh94742 -HULL NAY YANG TREE TOUT VETO</screen> - - <para>The rest of the description from the previous section applies here - as well.</para> - </sect2> - - <sect2> - <title>Diversion: a login prompt</title> - - <para>Before explaining how to generate one-time passwords, we should go - over an S/Key login prompt:</para> - - <screen>&prompt.user; <userinput>telnet himalia</userinput> -Trying 18.26.0.186... -Connected to himalia.lcs.mit.edu. -Escape character is '^]'. -s/key 92 hi52030 -<prompt>Password:</prompt></screen> - - <para>Note that, before prompting for a password, the login program - prints out the iteration number and seed which you will need in order - to generate the appropriate key. You will also find a useful feature - (not shown here): if you press return at the password prompt, the - login program will turn echo on, so you can see what you are typing. - This can be extremely useful if you are attempting to type in an S/Key - by hand, such as from a printout.</para> - - <para>If this machine were configured to disallow UNIX passwords over a - connection from my machine, the prompt would have also included the - annotation <literal>(s/key required)</literal>, indicating that only - S/Key one-time passwords will be accepted.</para> - </sect2> - - <sect2> - <title>Generating a single one-time password</title> - - <para>Now, to generate the one-time password needed to answer this login - prompt, we use a trusted machine and the <command>key</command> - program. (There are versions of the <command>key</command> program - from DOS and Windows machines, and there is an S/Key desk accessory - for Macintosh computers as well.) The command-line - <command>key</command> program takes as its parameters the iteration - count and seed; you can cut-and-paste right from the login prompt - starting at <literal>key</literal> to the end of the line. - Thus:</para> - - <screen>&prompt.user; <userinput>key 92 hi52030</userinput> ) pasted from previous section -Reminder - Do not use this program while logged in via telnet or rlogin. -<prompt>Enter secret password:</prompt> ) I typed my secret password -ADEN BED WOLF HAW HOT STUN</screen> - - <para>And in the other window:</para> - - <screen>s/key 92 hi52030 ) from previous section -<prompt>Password:</prompt> - (turning echo on) -<prompt>Password:</prompt>ADEN BED WOLF HAW HOT STUN -Last login: Wed Jun 28 15:31:00 from halloran-eldar.l -[etc.]</screen> - - <para>This is the easiest mechanism <emphasis>if</emphasis> you have a - trusted machine. There is a Java S/Key <command>key</command> applet, - <ulink URL="http://www.cs.umd.edu/~harry/jotp/src.html">The Java OTP - Calculator</ulink>, that you can download and run locally on any - Java supporting browser.</para> - </sect2> - - <sect2> - <title>Generating multiple one-time passwords</title> - - <para>Sometimes we have to go places where no trusted machines or - connections are available. In this case, it is possible to use the - <command>key</command> command to generate a number of one-time - passwords in the same command; these can then be printed out. For - example:</para> - - <screen>&prompt.user; <userinput>key -n 25 57 zz99999</userinput> -Reminder - Do not use this program while logged in via telnet or rlogin. -<prompt>Enter secret password:</prompt> -33: WALT THY MALI DARN NIT HEAD -34: ASK RICE BEAU GINA DOUR STAG -… -56: AMOS BOWL LUG FAT CAIN INCH -57: GROW HAYS TUN DISH CAR BALM</screen> - - <para>The <option>-n 25</option> requests twenty-five keys in sequence; - the <option>57</option> indicates the <emphasis>ending</emphasis> - iteration number; and the rest is as before. Note that these are - printed out in <emphasis>reverse</emphasis> order of eventual use. If - you are really paranoid, you might want to write the results down by - hand; otherwise you can cut-and-paste into <command>lpr</command>. - Note that each line shows both the iteration count and the one-time - password; you may still find it handy to scratch off passwords as you - use them.</para> - </sect2> - - <sect2> - <title>Restricting use of UNIX passwords</title> - - <para>The configuration file <filename>/etc/skey.access</filename> can - be used to configure restrictions on the use of UNIX passwords based - on the host name, user name, terminal port, or IP address of a login - session. The complete format of the file is documented in the - &man.skey.access.5; manual page; there are also some security - cautions there which should be read before depending on this file for - security.</para> - - <para>If there is no <filename>/etc/skey.access</filename> file (which - is the default state as FreeBSD is shipped), then all users will be - allowed to use UNIX passwords. If the file exists, however, then all - users will be required to use S/Key unless explicitly permitted to do - otherwise by configuration statements in the - <filename>skey.access</filename> file. In all cases, UNIX passwords - are permitted on the console.</para> - - <para>Here is a sample configuration file which illustrates the three - most common sorts of configuration statements:</para> - - <programlisting> -permit internet 18.26.0.0 255.255.0.0 -permit user jrl -permit port ttyd0</programlisting> - - <para>The first line (<literal>permit internet</literal>) allows users - whose IP source address (which is vulnerable to spoofing) matches the - specified value and mask, to use UNIX passwords. This should not be - considered a security mechanism, but rather, a means to remind - authorized users that they are using an insecure network and need to - use S/Key for authentication.</para> - - <para>The second line (<literal>permit user</literal>) allows the - specified user to use UNIX passwords at any time. Generally speaking, - this should only be used for people who are either unable to use the - <command>key</command> program, like those with dumb terminals, or - those who are uneducable.</para> - - <para>The third line (<literal>permit port</literal>) allows all users - logging in on the specified terminal line to use UNIX passwords; this - would be used for dial-ups.</para> - </sect2> - </sect1> - - <sect1 id="kerberos"> - <title>Kerberos</title> - - <para><emphasis>Contributed by &a.markm; (based on contribution by - &a.md;).</emphasis></para> - - <para>Kerberos is a network add-on system/protocol that allows users to - authenticate themselves through the services of a secure server. - Services such as remote login, remote copy, secure inter-system file - copying and other high-risk tasks are made considerably safer and more - controllable.</para> - - <para>The following instructions can be used as a guide on how to set up - Kerberos as distributed for FreeBSD. However, you should refer to the - relevant manual pages for a complete description.</para> - - <para>In FreeBSD, the Kerberos is not that from the original 4.4BSD-Lite, - distribution, but eBones, which had been previously ported to FreeBSD - 1.1.5.1, and was sourced from outside the USA/Canada, and is thus - available to system owners outside those countries.</para> - - <para>For those needing to get a legal foreign distribution of this - software, please <emphasis>do not</emphasis> get it from a USA or Canada - site. You will get that site in <emphasis>big</emphasis> trouble! A - legal copy of this is available from <hostid - role="fqdn">ftp.internat.FreeBSD.org</hostid>, which is in South - Africa and an official FreeBSD mirror site.</para> - - <sect2> - <title>Creating the initial database</title> - - <para>This is done on the Kerberos server only. First make sure that - you do not have any old Kerberos databases around. You should change - to the directory <filename>/etc/kerberosIV</filename> and check that - only the following files are present:</para> - - <screen>&prompt.root; <userinput>cd /etc/kerberosIV</userinput> -&prompt.root; <userinput>ls</userinput> -README krb.conf krb.realms</screen> - - <para>If any additional files (such as <filename>principal.*</filename> - or <filename>master_key</filename>) exist, then use the - <command>kdb_destroy</command> command to destroy the old Kerberos - database, of if Kerberos is not running, simply delete the extra - files.</para> - - <para>You should now edit the <filename>krb.conf</filename> and - <filename>krb.realms</filename> files to define your Kerberos realm. - In this case the realm will be <filename>GRONDAR.ZA</filename> and the - server is <filename>grunt.grondar.za</filename>. We edit or create - the <filename>krb.conf</filename> file:</para> - - <screen>&prompt.root; <userinput>cat krb.conf</userinput> -GRONDAR.ZA -GRONDAR.ZA grunt.grondar.za admin server -CS.BERKELEY.EDU okeeffe.berkeley.edu -ATHENA.MIT.EDU kerberos.mit.edu -ATHENA.MIT.EDU kerberos-1.mit.edu -ATHENA.MIT.EDU kerberos-2.mit.edu -ATHENA.MIT.EDU kerberos-3.mit.edu -LCS.MIT.EDU kerberos.lcs.mit.edu -TELECOM.MIT.EDU bitsy.mit.edu -ARC.NASA.GOV trident.arc.nasa.gov</screen> - - <para>In this case, the other realms do not need to be there. They are - here as an example of how a machine may be made aware of multiple - realms. You may wish to not include them for simplicity.</para> - - <para>The first line names the realm in which this system works. The - other lines contain realm/host entries. The first item on a line is a - realm, and the second is a host in that realm that is acting as a - “key distribution centre”. The words <literal>admin - server</literal> following a hosts name means that host also - provides an administrative database server. For further explanation - of these terms, please consult the Kerberos man pages.</para> - - <para>Now we have to add <hostid role="fqdn">grunt.grondar.za</hostid> - to the <filename>GRONDAR.ZA</filename> realm and also add an entry to - put all hosts in the <hostid role="domainname">.grondar.za</hostid> - domain in the <filename>GRONDAR.ZA</filename> realm. The - <filename>krb.realms</filename> file would be updated as - follows:</para> - - <screen>&prompt.root; <userinput>cat krb.realms</userinput> -grunt.grondar.za GRONDAR.ZA -.grondar.za GRONDAR.ZA -.berkeley.edu CS.BERKELEY.EDU -.MIT.EDU ATHENA.MIT.EDU -.mit.edu ATHENA.MIT.EDU</screen> - - <para>Again, the other realms do not need to be there. They are here as - an example of how a machine may be made aware of multiple realms. You - may wish to remove them to simplify things.</para> - - <para>The first line puts the <emphasis>specific</emphasis> system into - the named realm. The rest of the lines show how to default systems of - a particular subdomain to a named realm.</para> - - <para>Now we are ready to create the database. This only needs to run - on the Kerberos server (or Key Distribution Centre). Issue the - <command>kdb_init</command> command to do this:</para> - - <screen>&prompt.root; <userinput>kdb_init</userinput> -<prompt>Realm name [default ATHENA.MIT.EDU ]:</prompt> <userinput>GRONDAR.ZA</userinput> -You will be prompted for the database Master Password. -It is important that you NOT FORGET this password. - -<prompt>Enter Kerberos master key:</prompt> </screen> - - <para>Now we have to save the key so that servers on the local machine - can pick it up. Use the <command>kstash</command> command to do - this.</para> - - <screen>&prompt.root; <userinput>kstash</userinput> - -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE!</screen> - - <para>This saves the encrypted master password in - <filename>/etc/kerberosIV/master_key</filename>.</para> - </sect2> - - <sect2> - <title>Making it all run</title> - - <para>Two principals need to be added to the database for - <emphasis>each</emphasis> system that will be secured with Kerberos. - Their names are <literal>kpasswd</literal> and <literal>rcmd</literal> - These two principals are made for each system, with the instance being - the name of the individual system.</para> - - <para>These daemons, <command>kpasswd</command> and - <command>rcmd</command> allow other systems to change Kerberos - passwords and run commands like <command>rcp</command>, - <command>rlogin</command> and <command>rsh</command>.</para> - - <para>Now let's add these entries:</para> - - <screen>&prompt.root; <userinput>kdb_edit</userinput> -Opening database... - -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -<prompt>Principal name:</prompt> <userinput>passwd</userinput> -<prompt>Instance:</prompt> <userinput>grunt</userinput> - -<Not found>, <prompt>Create [y] ?</prompt> <userinput>y</userinput> - -Principal: passwd, Instance: grunt, kdc_key_ver: 1 -<prompt>New Password:</prompt> <---- enter RANDOM here -Verifying password - -<prompt>New Password:</prompt> <---- enter RANDOM here - -<prompt>Random password [y] ?</prompt> <userinput>y</userinput> - -Principal's new key version = 1 -<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt> -<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> -<prompt>Attributes [ 0 ] ?</prompt> -Edit O.K. -<prompt>Principal name:</prompt> <userinput>rcmd</userinput> -<prompt>Instance:</prompt> <userinput>grunt</userinput> - -<Not found>, <prompt>Create [y] ?</prompt> - -Principal: rcmd, Instance: grunt, kdc_key_ver: 1 -<prompt>New Password:</prompt> <---- enter RANDOM here -Verifying password - -<prompt>New Password:</prompt> <---- enter RANDOM here - -<prompt>Random password [y] ?</prompt> - -Principal's new key version = 1 -<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt> -<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> -<prompt>Attributes [ 0 ] ?</prompt> -Edit O.K. -<prompt>Principal name:</prompt> <---- null entry here will cause an exit</screen> - </sect2> - - <sect2> - <title>Creating the server file</title> - - <para>We now have to extract all the instances which define the services - on each machine. For this we use the <command>ext_srvtab</command> - command. This will create a file which must be copied or moved - <emphasis>by secure means</emphasis> to each Kerberos client's - /etc/kerberosIV directory. This file must be present on each server - and client, and is crucial to the operation of Kerberos.</para> - - - <screen>&prompt.root; <userinput>ext_srvtab grunt</userinput> -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Generating 'grunt-new-srvtab'....</screen> - - <para>Now, this command only generates a temporary file which must be - renamed to <filename>srvtab</filename> so that all the server can pick - it up. Use the <command>mv</command> command to move it into place on - the original system:</para> - - <screen>&prompt.root; <userinput>mv grunt-new-srvtab srvtab</userinput></screen> - - <para>If the file is for a client system, and the network is not deemed - safe, then copy the - <filename><replaceable>client</replaceable>-new-srvtab</filename> to - removable media and transport it by secure physical means. Be sure to - rename it to <filename>srvtab</filename> in the client's - <filename>/etc/kerberosIV</filename> directory, and make sure it is - mode 600:</para> - - <screen>&prompt.root; <userinput>mv grumble-new-srvtab srvtab</userinput> -&prompt.root; <userinput>chmod 600 srvtab</userinput></screen> - </sect2> - - <sect2> - <title>Populating the database</title> - - <para>We now have to add some user entries into the database. First - let's create an entry for the user <username>jane</username>. Use the - <command>kdb_edit</command> command to do this:</para> - - <screen>&prompt.root; <userinput>kdb_edit</userinput> -Opening database... - -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -<prompt>Principal name:</prompt> <userinput>jane</userinput> -<prompt>Instance:</prompt> - -<Not found>, <prompt>Create [y] ?</prompt> <userinput>y</userinput> - -Principal: jane, Instance: , kdc_key_ver: 1 -<prompt>New Password:</prompt> <---- enter a secure password here -Verifying password - -<prompt>New Password:</prompt> <---- re-enter the password here -Principal's new key version = 1 -<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt> -<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> -<prompt>Attributes [ 0 ] ?</prompt> -Edit O.K. -<prompt>Principal name:</prompt> <---- null entry here will cause an exit</screen> - </sect2> - - <sect2> - <title>Testing it all out</title> - - <para>First we have to start the Kerberos daemons. NOTE that if you - have correctly edited your <filename>/etc/rc.conf</filename> then this - will happen automatically when you reboot. This is only necessary on - the Kerberos server. Kerberos clients will automagically get what - they need from the <filename>/etc/kerberosIV</filename> - directory.</para> - - <screen>&prompt.root; <userinput>kerberos &</userinput> -Kerberos server starting -Sleep forever on error -Log file is /var/log/kerberos.log -Current Kerberos master key version is 1. - -Master key entered. BEWARE! - -Current Kerberos master key version is 1 -Local realm: GRONDAR.ZA -&prompt.root; <userinput>kadmind -n &</userinput> -KADM Server KADM0.0A initializing -Please do not use 'kill -9' to kill this job, use a -regular kill instead - -Current Kerberos master key version is 1. - -Master key entered. BEWARE!</screen> - - <para>Now we can try using the <command>kinit</command> command to get a - ticket for the id <username>jane</username> that we created - above:</para> - - <screen>&prompt.user; <userinput>kinit jane</userinput> -MIT Project Athena (grunt.grondar.za) -Kerberos Initialization for "jane" -<prompt>Password:</prompt> </screen> - - <para>Try listing the tokens using <command>klist</command> to see if we - really have them:</para> - - <screen>&prompt.user; <userinput>klist</userinput> -Ticket file: /tmp/tkt245 -Principal: jane@GRONDAR.ZA - - Issued Expires Principal -Apr 30 11:23:22 Apr 30 19:23:22 krbtgt.GRONDAR.ZA@GRONDAR.ZA</screen> - - <para>Now try changing the password using <command>passwd</command> to - check if the kpasswd daemon can get authorization to the Kerberos - database:</para> - - <screen>&prompt.user; <userinput>passwd</userinput> -realm GRONDAR.ZA -<prompt>Old password for jane:</prompt> -<prompt>New Password for jane:</prompt> -Verifying password -<prompt>New Password for jane:</prompt> -Password changed.</screen> - </sect2> - - <sect2> - <title>Adding <command>su</command> privileges</title> - - <para>Kerberos allows us to give <emphasis>each</emphasis> user who - needs root privileges their own <emphasis>separate</emphasis> - <command>su</command>password. We could now add an id which is - authorized to <command>su</command> to <username>root</username>. - This is controlled by having an instance of <username>root</username> - associated with a principal. Using <command>kdb_edit</command> we can - create the entry <literal>jane.root</literal> in the Kerberos - database:</para> - - <screen>&prompt.root; <userinput>kdb_edit</userinput> -Opening database... - -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -<prompt>Principal name:</prompt> <userinput>jane</userinput> -<prompt>Instance:</prompt> <userinput>root</userinput> - -<Not found>, Create [y] ? y - -Principal: jane, Instance: root, kdc_key_ver: 1 -<prompt>New Password:</prompt> <---- enter a SECURE password here -Verifying password - -<prompt>New Password:</prompt> <---- re-enter the password here - -Principal's new key version = 1 -<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt> -<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> <userinput>12</userinput> <--- Keep this short! -<prompt>Attributes [ 0 ] ?</prompt> -Edit O.K. -<prompt>Principal name:</prompt> <---- null entry here will cause an exit</screen> - - <para>Now try getting tokens for it to make sure it works:</para> - - <screen>&prompt.root; <userinput>kinit jane.root</userinput> -MIT Project Athena (grunt.grondar.za) -Kerberos Initialization for "jane.root" -<prompt>Password:</prompt></screen> - - <para>Now we need to add the user to root's <filename>.klogin</filename> - file:</para> - - <screen>&prompt.root; <userinput>cat /root/.klogin</userinput> -jane.root@GRONDAR.ZA</screen> - - <para>Now try doing the <command>su</command>:</para> - - <screen>&prompt.user; <prompt>su</prompt> -<prompt>Password:</prompt></screen> - - <para>and take a look at what tokens we have:</para> - - <screen>&prompt.root; klist -Ticket file: /tmp/tkt_root_245 -Principal: jane.root@GRONDAR.ZA - - Issued Expires Principal -May 2 20:43:12 May 3 04:43:12 krbtgt.GRONDAR.ZA@GRONDAR.ZA</screen> - </sect2> - - <sect2> - <title>Using other commands</title> - - <para>In an earlier example, we created a principal called - <literal>jane</literal> with an instance <literal>root</literal>. - This was based on a user with the same name as the principal, and this - is a Kerberos default; that a - <literal><principal>.<instance></literal> of the form - <literal><username>.</literal><literal>root</literal> will allow - that <literal><username></literal> to <command>su</command> to - root if the necessary entries are in the <filename>.klogin</filename> - file in <username>root</username>'s home directory:</para> - - <screen>&prompt.root; <userinput>cat /root/.klogin</userinput> -jane.root@GRONDAR.ZA</screen> - - <para>Likewise, if a user has in their own home directory lines of the - form:</para> - - <screen>&prompt.user; <userinput>cat ~/.klogin</userinput> -jane@GRONDAR.ZA -jack@GRONDAR.ZA</screen> - - <para>This allows anyone in the <filename>GRONDAR.ZA</filename> realm - who has authenticated themselves to <username>jane</username> or - <username>jack</username> (via <command>kinit</command>, see above) - access to <command>rlogin</command> to <username>jane</username>'s - account or files on this system (<hostid>grunt</hostid>) via - <command>rlogin</command>, <command>rsh</command> or - <command>rcp</command>.</para> - - <para>For example, Jane now logs into another system, using - Kerberos:</para> - - <screen>&prompt.user; <userinput>kinit</userinput> -MIT Project Athena (grunt.grondar.za) -<prompt>Password:</prompt> -%prompt.user; <userinput>rlogin grunt</userinput> -Last login: Mon May 1 21:14:47 from grumble -Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 - The Regents of the University of California. All rights reserved. - -FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen> - - <para>Or Jack logs into Jane's account on the same machine (Jane having - set up the <filename>.klogin</filename> file as above, and the person - in charge of Kerberos having set up principal - <emphasis>jack</emphasis> with a null instance:</para> - - <screen>&prompt.user; <userinput>kinit</userinput> -&prompt.user; <userinput>rlogin grunt -l jane</userinput> -MIT Project Athena (grunt.grondar.za) -<prompt>Password:</prompt> -Last login: Mon May 1 21:16:55 from grumble -Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 - The Regents of the University of California. All rights reserved. -FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen> - </sect2> - </sect1> - - <sect1 id="firewalls"> - <title>Firewalls</title> - - <para><emphasis>Contributed by &a.gpalmer; and &a.alex;.</emphasis></para> - - <para>Firewalls are an area of increasing interest for people who are - connected to the Internet, and are even finding applications on private - networks to provide enhanced security. This section will hopefully - explain what firewalls are, how to use them, and how to use the - facilities provided in the FreeBSD kernel to implement them.</para> - - <note> - <para>People often think that having a firewall between your companies - internal network and the “Big Bad Internet” will solve all - your security problems.</para> - - <para>It may help, but a poorly setup firewall system is more of a - security risk than not having one at all. A firewall can only add - another layer of security to your systems, but they will not be able - to stop a really determined cracker from penetrating your internal - network. If you let internal security lapse because you believe your - firewall to be impenetrable, you have just made the crackers job that - bit easier.</para> - </note> - - <sect2> - <title>What is a firewall?</title> - - <para>There are currently two distinct types of firewalls in common use - on the Internet today. The first type is more properly called a - <emphasis>packet filtering router</emphasis>, where the kernel on a - multi-homed machine chooses whether to forward or block packets based - on a set of rules. The second type, known as <emphasis>proxy - servers</emphasis>, rely on daemons to provide authentication and to - forward packets, possibly on a multi-homed machine which has kernel - packet forwarding disabled.</para> - - <para>Sometimes sites combine the two types of firewalls, so that only a - certain machine (known as a <emphasis>bastion host</emphasis>) is - allowed to send packets through a packet filtering router onto an - internal network. Proxy services are run on the bastion host, which - are generally more secure than normal authentication - mechanisms.</para> - - <para>FreeBSD comes with a kernel packet filter (known as - <application>IPFW</application>), which is what the rest of this - section will concentrate on. Proxy servers can be built on FreeBSD - from third party software, but there is such a variety of proxy - servers available that it would be impossible to cover them in this - document.</para> - - <sect3 id="firewalls-packet-filters"> - <title>Packet filtering routers</title> - - <para>A router is a machine which forwards packets between two or more - networks. A packet filtering router has an extra piece of code in - its kernel, which compares each packet to a list of rules before - deciding if it should be forwarded or not. Most modern IP routing - software has packet filtering code in it, which defaults to - forwarding all packets. To enable the filters, you need to define a - set of rules for the filtering code, so that it can decide if the - packet should be allowed to pass or not.</para> - - <para>To decide if a packet should be passed on or not, the code looks - through its set of rules for a rule which matches the contents of - this packets headers. Once a match is found, the rule action is - obeyed. The rule action could be to drop the packet, to forward the - packet, or even to send an ICMP message back to the originator. - Only the first match counts, as the rules are searched in order. - Hence, the list of rules can be referred to as a “rule - chain”.</para> - - <para>The packet matching criteria varies depending on the software - used, but typically you can specify rules which depend on the source - IP address of the packet, the destination IP address, the source - port number, the destination port number (for protocols which - support ports), or even the packet type (UDP, TCP, ICMP, - etc).</para> - </sect3> - - <sect3 id="firewalls-proxy-servers"> - <title>Proxy servers</title> - - <para>Proxy servers are machines which have had the normal system - daemons (telnetd, ftpd, etc) replaced with special servers. These - servers are called <emphasis>proxy servers</emphasis> as they - normally only allow onward connections to be made. This enables you - to run (for example) a proxy telnet server on your firewall host, - and people can telnet in to your firewall from the outside, go - through some authentication mechanism, and then gain access to the - internal network (alternatively, proxy servers can be used for - signals coming from the internal network and heading out).</para> - - <para>Proxy servers are normally more secure than normal servers, and - often have a wider variety of authentication mechanisms available, - including “one-shot” password systems so that even if - someone manages to discover what password you used, they will not be - able to use it to gain access to your systems as the password - instantly expires. As they do not actually give users access to the - host machine, it becomes a lot more difficult for someone to install - backdoors around your security system.</para> - - <para>Proxy servers often have ways of restricting access further, so - that only certain hosts can gain access to the servers, and often - they can be set up so that you can limit which users can talk to - which destination machine. Again, what facilities are available - depends largely on what proxy software you choose.</para> - </sect3> - </sect2> - - <sect2> - <title>What does IPFW allow me to do?</title> - - <para><application>IPFW</application>, the software supplied with - FreeBSD, is a packet filtering and accounting system which resides in - the kernel, and has a user-land control utility, - &man.ipfw.8;. Together, they allow you to define and query the - rules currently used by the kernel in its routing decisions.</para> - - <para>There are two related parts to <application>IPFW</application>. - The firewall section allows you to perform packet filtering. There is - also an IP accounting section which allows you to track usage of your - router, based on similar rules to the firewall section. This allows - you to see (for example) how much traffic your router is getting from - a certain machine, or how much WWW (World Wide Web) traffic it is - forwarding.</para> - - <para>As a result of the way that <application>IPFW</application> is - designed, you can use <application>IPFW</application> on non-router - machines to perform packet filtering on incoming and outgoing - connections. This is a special case of the more general use of - <application>IPFW</application>, and the same commands and techniques - should be used in this situation.</para> - </sect2> - - <sect2> - <title>Enabling IPFW on FreeBSD</title> - - <para>As the main part of the <application>IPFW</application> system - lives in the kernel, you will need to add one or more options to your - kernel configuration file, depending on what facilities you want, and - recompile your kernel. See <link linkend="kernelconfig">reconfiguring - the kernel</link> for more details on how to recompile your - kernel.</para> - - <para>There are currently three kernel configuration options relevant to - IPFW:</para> - - <variablelist> - <varlistentry> - <term><literal>options IPFIREWALL</literal></term> - - <listitem> - <para>Compiles into the kernel the code for packet - filtering.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPFIREWALL_VERBOSE</literal></term> - - <listitem> - <para>Enables code to allow logging of packets through - &man.syslogd.8;. Without this option, even if you specify - that packets should be logged in the filter rules, nothing will - happen.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPFIREWALL_VERBOSE_LIMIT=10</literal></term> - - <listitem> - <para>Limits the number of packets logged through - &man.syslogd.8; on a per entry basis. You may wish to use - this option in hostile environments in which you want to log - firewall activity, but do not want to be open to a denial of - service attack via syslog flooding.</para> - - <para>When a chain entry reaches the packet limit specified, - logging is turned off for that particular entry. To resume - logging, you will need to reset the associated counter using the - &man.ipfw.8; utility:</para> - - <screen>&prompt.root; <userinput>ipfw zero 4500</userinput></screen> - <para>Where 4500 is the chain entry you wish to continue - logging.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Previous versions of FreeBSD contained an - <literal>IPFIREWALL_ACCT</literal> option. This is now obsolete as - the firewall code automatically includes accounting - facilities.</para> - </sect2> - - <sect2> - <title>Configuring IPFW</title> - - <para>The configuration of the <application>IPFW</application> software - is done through the &man.ipfw.8; utility. The syntax for this - command looks quite complicated, but it is relatively simple once you - understand its structure.</para> - - <para>There are currently four different command categories used by the - utility: addition/deletion, listing, flushing, and clearing. - Addition/deletion is used to build the rules that control how packets - are accepted, rejected, and logged. Listing is used to examine the - contents of your rule set (otherwise known as the chain) and packet - counters (accounting). Flushing is used to remove all entries from - the chain. Clearing is used to zero out one or more accounting - entries.</para> - - <sect3> - <title>Altering the IPFW rules</title> - - <para>The syntax for this form of the command is: - <cmdsynopsis> - <command>ipfw</command> - <arg>-N</arg> - <arg choice="plain">command</arg> - <arg>index</arg> - <arg choice="plain">action</arg> - <arg>log</arg> - <arg choice="plain">protocol</arg> - <arg choice="plain">addresses</arg> - <arg>options</arg> - </cmdsynopsis></para> - - <para>There is one valid flag when using this form of the - command:</para> - - <variablelist> - <varlistentry> - <term>-N</term> - - <listitem> - <para>Resolve addresses and service names in output.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <emphasis>command</emphasis> given can be shortened to the - shortest unique form. The valid <emphasis>commands</emphasis> - are:</para> - - <variablelist> - <varlistentry> - <term>add</term> - - <listitem> - <para>Add an entry to the firewall/accounting rule list</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>delete</term> - - <listitem> - <para>Delete an entry from the firewall/accounting rule - list</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Previous versions of <application>IPFW</application> used - separate firewall and accounting entries. The present version - provides packet accounting with each firewall entry.</para> - - <para>If an <emphasis>index</emphasis> value is supplied, it used to - place the entry at a specific point in the chain. Otherwise, the - entry is placed at the end of the chain at an index 100 greater than - the last chain entry (this does not include the default policy, rule - 65535, deny).</para> - - <para>The <literal>log</literal> option causes matching rules to be - output to the system console if the kernel was compiled with - <literal>IPFIREWALL_VERBOSE</literal>.</para> - - <para>Valid <emphasis>actions</emphasis> are:</para> - - <variablelist> - <varlistentry> - <term>reject</term> - - <listitem> - <para>Drop the packet, and send an ICMP host or port unreachable - (as appropriate) packet to the source.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>allow</term> - - <listitem> - <para>Pass the packet on as normal. (aliases: - <literal>pass</literal> and - <literal>accept</literal>)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>deny</term> - - <listitem> - <para>Drop the packet. The source is not notified via an - ICMP message (thus it appears that the packet never - arrived at the destination).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>count</term> - - <listitem> - <para>Update packet counters but do not allow/deny the packet - based on this rule. The search continues with the next chain - entry.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Each <emphasis>action</emphasis> will be recognized by the - shortest unambiguous prefix.</para> - - <para>The <emphasis>protocols</emphasis> which can be specified - are:</para> - - <variablelist> - <varlistentry> - <term>all</term> - - <listitem> - <para>Matches any IP packet</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>icmp</term> - - <listitem> - <para>Matches ICMP packets</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tcp</term> - - <listitem> - <para>Matches TCP packets</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>udp</term> - - <listitem> - <para>Matches UDP packets</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <emphasis>address</emphasis> specification is:</para> - - <cmdsynopsis> - <arg choice="plain">from</arg> - <arg choice="plain"><replaceable>address/mask</replaceable></arg><arg><replaceable>port</replaceable></arg> - <arg choice="plain">to</arg> - <arg choice="plain"><replaceable>address/mark</replaceable></arg><arg><replaceable>port</replaceable></arg> - <arg>via <replaceable>interface</replaceable></arg> - </cmdsynopsis> - - <para>You can only specify <replaceable>port</replaceable> in - conjunction with <emphasis>protocols</emphasis> which support ports - (UDP and TCP).</para> - - <para>The <option>via</option> is optional and may specify the IP - address or domain name of a local IP interface, or an interface name - (e.g. <devicename>ed0</devicename>) to match only packets coming - through this interface. Interface unit numbers can be specified - with an optional wildcard. For example, <literal>ppp*</literal> - would match all kernel PPP interfaces.</para> - - <para>The syntax used to specify an - <replaceable>address/mask</replaceable> is: - - <screen><replaceable>address</replaceable></screen> - - or - - <screen><replaceable>address</replaceable>/<replaceable>mask-bits</replaceable></screen> - - or - - <screen><replaceable>address</replaceable>:<replaceable>mask-pattern</replaceable></screen> - </para> - - <para>A valid hostname may be specified in place of the IP address. - <option><replaceable>mask-bits</replaceable></option> is a decimal - number representing how many bits in the address mask should be set. - e.g. specifying <literal>192.216.222.1/24</literal> will create a - mask which will allow any address in a class C subnet (in this case, - 192.216.222) to be matched. - <option><replaceable>mask-pattern</replaceable></option> is an IP - address which will be logically AND'ed with the address given. The - keyword <literal>any</literal> may be used to specify “any IP - address”.</para> - - <para>The port numbers to be blocked are specified as: - - <cmdsynopsis> - <arg choice="plain"><replaceable>port</replaceable><arg>,<replaceable>port</replaceable><arg>,<replaceable>port</replaceable><arg>…</arg></arg></arg></arg> - </cmdsynopsis> - - to specify either a single port or a list of ports, or - - <cmdsynopsis> - <arg choice="plain"><replaceable>port</replaceable>-<replaceable>port</replaceable></arg> - </cmdsynopsis> - - to specify a range of ports. You may also combine a single range - with a list, but the range must always be specified first.</para> - - <para>The <emphasis>options</emphasis> available are:</para> - - <variablelist> - <varlistentry> - <term>frag</term> - - <listitem> - <para>Matches if the packet is not the first fragment of the - datagram.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>in</term> - - <listitem> - <para>Matches if the packet is on the way in.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>out</term> - - <listitem> - <para>Matches if the packet is on the way out.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ipoptions <replaceable>spec</replaceable></term> - - <listitem> - <para>Matches if the IP header contains the comma separated list - of options specified in <replaceable>spec</replaceable>. The - supported list of IP options are: <literal>ssrr</literal> - (strict source route), <literal>lsrr</literal> (loose source - route), <literal>rr</literal> (record packet route), and - <literal>ts</literal> (timestamp). The absence of a - particular option may be denoted with a leading - <literal>!</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>established</term> - - <listitem> - <para>Matches if the packet is part of an already established - TCP connection (i.e. it has the RST or ACK bits set). You can - optimize the performance of the firewall by placing - <emphasis>established</emphasis> rules early in the - chain.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>setup</term> - - <listitem> - <para>Matches if the packet is an attempt to establish a TCP - connection (the SYN bit set is set but the ACK bit is - not).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tcpflags <replaceable>flags</replaceable></term> - - <listitem> - <para>Matches if the TCP header contains the comma separated - list of <replaceable>flags</replaceable>. The supported flags - are <literal>fin</literal>, <literal>syn</literal>, - <literal>rst</literal>, <literal>psh</literal>, - <literal>ack</literal>, and <literal>urg</literal>. The - absence of a particular flag may be indicated by a leading - <literal>!</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>icmptypes <replaceable>types</replaceable></term> - - <listitem> - <para>Matches if the ICMP type is present in the list - <replaceable>types</replaceable>. The list may be specified - as any combination of ranges and/or individual types separated - by commas. Commonly used ICMP types are: <literal>0</literal> - echo reply (ping reply), <literal>3</literal> destination - unreachable, <literal>5</literal> redirect, - <literal>8</literal> echo request (ping request), and - <literal>11</literal> time exceeded (used to indicate TTL - expiration as with &man.traceroute.8;).</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3> - <title>Listing the IPFW rules</title> - - <para>The syntax for this form of the command is: - <cmdsynopsis> - <command>ipfw</command> - <arg>-a</arg> - <arg>-t</arg> - <arg>-N</arg> - <arg choice="plain">l</arg> - </cmdsynopsis></para> - - <para>There are three valid flags when using this form of the - command:</para> - - <variablelist> - <varlistentry> - <term>-a</term> - - <listitem> - <para>While listing, show counter values. This option is the - only way to see accounting counters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-t</term> - - <listitem> - <para>Display the last match times for each chain entry. The - time listing is incompatible with the input syntax used by the - &man.ipfw.8; utility.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-N</term> - - <listitem> - <para>Attempt to resolve given addresses and service - names.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3> - <title>Flushing the IPFW rules</title> - - <para>The syntax for flushing the chain is: - <cmdsynopsis> - <command>ipfw</command> - <arg choice="plain">flush</arg> - </cmdsynopsis></para> - - <para>This causes all entries in the firewall chain to be removed - except the fixed default policy enforced by the kernel (index - 65535). Use caution when flushing rules, the default deny policy - will leave your system cut off from the network until allow entries - are added to the chain.</para> - </sect3> - - <sect3> - <title>Clearing the IPFW packet counters</title> - - <para>The syntax for clearing one or more packet counters is: - <cmdsynopsis> - <command>ipfw</command> - <arg choice="plain">zero</arg> - <arg choice="opt"><replaceable>index</replaceable></arg> - </cmdsynopsis></para> - - <para>When used without an <replaceable>index</replaceable> argument, - all packet counters are cleared. If an - <replaceable>index</replaceable> is supplied, the clearing operation - only affects a specific chain entry.</para> - </sect3> - </sect2> - - <sect2> - <title>Example commands for ipfw</title> - - <para>This command will deny all packets from the host <hostid - role="fqdn">evil.crackers.org</hostid> to the telnet port of the - host <hostid role="fqdn">nice.people.org</hostid> by being forwarded - by the router:</para> - - <screen>&prompt.root <userinput>ipfw add deny tcp from evil.crackers.org to nice.people.org 23</userinput></screen> - - <para>The next example denies and logs any TCP traffic from the entire - <hostid role="domainname">crackers.org</hostid> network (a class C) to - the <hostid role="fqdn">nice.people.org</hostid> machine (any - port).</para> - - <screen>&prompt.root; <userinput>ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org</userinput></screen> - - <para>If you do not want people sending X sessions to your internal - network (a subnet of a class C), the following command will do the - necessary filtering:</para> - - <screen>&prompt.root; <userinput>ipfw add deny tcp from any to my.org/28 6000 setup</userinput></screen> - - <para>To see the accounting records: - - <screen>&prompt.root; <userinput>ipfw -a list</userinput></screen> - - or in the short form - - <screen>&prompt.root; <userinput>ipfw -a l</userinput></screen> - </para> - - <para>You can also see the last time a chain entry was matched - with:</para> - - <screen>&prompt.root; <userinput>ipfw -at l</userinput></screen> - </sect2> - - <sect2> - <title>Building a packet filtering firewall</title> - - <note> - <para>The following suggestions are just that: suggestions. The - requirements of each firewall are different and I cannot tell you - how to build a firewall to meet your particular requirements.</para> - </note> - - <para>When initially setting up your firewall, unless you have a test - bench setup where you can configure your firewall host in a controlled - environment, I strongly recommend you use the logging version of the - commands and enable logging in the kernel. This will allow you to - quickly identify problem areas and cure them without too much - disruption. Even after the initial setup phase is complete, I - recommend using the logging for of `deny' as it allows tracing of - possible attacks and also modification of the firewall rules if your - requirements alter.</para> - - <note> - <para>If you use the logging versions of the <command>accept</command> - command, it can generate <emphasis>large</emphasis> amounts of log - data as one log line will be generated for every packet that passes - through the firewall, so large ftp/http transfers, etc, will really - slow the system down. It also increases the latencies on those - packets as it requires more work to be done by the kernel before the - packet can be passed on. syslogd with also start using up a lot - more processor time as it logs all the extra data to disk, and it - could quite easily fill the partition <filename>/var/log</filename> - is located on.</para> - </note> - - <para>You should enable your firewall from - <filename>/etc/rc.conf.local</filename> or - <filename>/etc/rc.conf</filename>. The associated manpage explains - which knobs to fiddle and lists some preset firewall configurations. - If you do not use a preset configuration, <command>ipfw list</command> - will output the current ruleset into a file that you can - pass to <filename>rc.conf</filename>. If you do not use - <filename>/etc/rc.conf.local</filename> or - <filename>/etc/rc.conf</filename> to enable your firewall, - it is important to make sure your firewall is enabled before - any IP interfaces are configured. - </para> - - <para>The next problem is what your firewall should actually - <emphasis>do</emphasis>! This is largely dependent on what access to - your network you want to allow from the outside, and how much access - to the outside world you want to allow from the inside. Some general - rules are:</para> - - <itemizedlist> - <listitem> - <para>Block all incoming access to ports below 1024 for TCP. This is - where most of the security sensitive services are, like finger, - SMTP (mail) and telnet.</para> - </listitem> - - <listitem> - <para>Block <emphasis>all</emphasis> incoming UDP traffic. There - are very few useful services that travel over UDP, and what useful - traffic there is is normally a security threat (e.g. Suns RPC and - NFS protocols). This has its disadvantages also, since UDP is a - connectionless protocol, denying incoming UDP traffic also blocks - the replies to outgoing UDP traffic. This can cause a problem for - people (on the inside) using external archie (prospero) servers. - If you want to allow access to archie, you'll have to allow - packets coming from ports 191 and 1525 to any internal UDP port - through the firewall. ntp is another service you may consider - allowing through, which comes from port 123.</para> - </listitem> - - <listitem> - <para>Block traffic to port 6000 from the outside. Port 6000 is the - port used for access to X11 servers, and can be a security threat - (especially if people are in the habit of doing <command>xhost - +</command> on their workstations). X11 can actually use a - range of ports starting at 6000, the upper limit being how many X - displays you can run on the machine. The upper limit as defined - by RFC 1700 (Assigned Numbers) is 6063.</para> - </listitem> - - <listitem> - <para>Check what ports any internal servers use (e.g. SQL servers, - etc). It is probably a good idea to block those as well, as they - normally fall outside the 1-1024 range specified above.</para> - </listitem> - </itemizedlist> - - <para>Another checklist for firewall configuration is available from - CERT at <ulink - URL="ftp://ftp.cert.org/pub/tech_tips/packet_filtering">ftp://ftp.cert.org/pub/tech_tips/packet_filtering</ulink></para> - - <para>As I said above, these are only <emphasis>guidelines</emphasis>. - You will have to decide what filter rules you want to use on your - firewall yourself. I cannot accept ANY responsibility if someone - breaks into your network, even if you follow the advice given - above.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/serialcomms/chapter.sgml b/en/handbook/serialcomms/chapter.sgml deleted file mode 100644 index 1d4f043139..0000000000 --- a/en/handbook/serialcomms/chapter.sgml +++ /dev/null @@ -1,2731 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.12 1999-08-05 20:48:25 nik Exp $ ---> - -<chapter id="serialcomms"> - <title>Serial Communications</title> - - <sect1 id="serial"> - <title>Serial Basics</title> - - <para><emphasis>Assembled from FAQ.</emphasis></para> - - <para>This section should give you some general information about serial - ports. If you do not find what you want here, check into the Terminal - and Dialup sections of the handbook.</para> - - <para>The <filename>ttyd<replaceable>X</replaceable></filename> (or - <filename>cuaa<replaceable>X</replaceable></filename>) device is the - regular device you will want to open for your applications. When a - process opens the device, it will have a default set of terminal I/O - settings. You can see these settings with the command</para> - - <screen>&prompt.root; <userinput>stty -a -f /dev/ttyd1</userinput></screen> - - <para>When you change the settings to this device, the settings are in - effect until the device is closed. When it is reopened, it goes back to - the default set. To make changes to the default set, you can open and - adjust the settings of the “initial state” device. For - example, to turn on <acronym>CLOCAL</acronym> mode, 8 bits, and - <emphasis>XON/XOFF</emphasis> flow control by default for ttyd5, - do:</para> - - <screen>&prompt.root; <userinput>stty -f /dev/ttyid5 clocal cs8 ixon ixoff</userinput></screen> - - <para>A good place to do this is in <filename>/etc/rc.serial</filename>. - Now, an application will have these settings by default when it opens - <filename>ttyd5</filename>. It can still change these settings to its - liking, though.</para> - - <para>You can also prevent certain settings from being changed by an - application by making adjustments to the “lock state” - device. For example, to lock the speed of <filename>ttyd5</filename> to - 57600 bps, do</para> - - <screen>&prompt.root; <userinput>stty -f /dev/ttyld5 57600</userinput></screen> - - <para>Now, an application that opens <filename>ttyd5</filename> and tries - to change the speed of the port will be stuck with 57600 bps.</para> - - <para>Naturally, you should make the initial state and lock state devices - writable only by <username>root</username>. The - <filename>MAKEDEV</filename> script does <emphasis>not</emphasis> do - this when it creates the device entries.</para> - </sect1> - - <sect1 id="term"> - <title>Terminals</title> - - <para><emphasis>Contributed by &a.kelly; 28 July 1996</emphasis></para> - - <para>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.</para> - - <sect2 id="term-uses"> - <title>Uses and Types of Terminals</title> - - <para>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.</para> - - <para>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 <command>xterm</command> window in the X Window - System.</para> - - <para>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.</para> - - <para>For FreeBSD, there are three kinds of terminals:</para> - - <itemizedlist> - <listitem> - <para><link linkend="term-dumb">Dumb terminals</link></para> - </listitem> - - <listitem> - <para><link linkend="term-pcs">PCs acting as terminals</link></para> - </listitem> - - <listitem> - <para><link linkend="term-x">X terminals</link></para> - </listitem> - </itemizedlist> - - <para>The remaining subsections describe each kind.</para> - - <sect3 id="term-dumb"> - <title>Dumb Terminals</title> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - </sect3> - - <sect3 id="term-pcs"> - <title>PCs Acting As Terminals</title> - - <para>If a <link linkend="term-dumb">dumb terminal</link> 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 <emphasis>terminal emulation</emphasis> - software to run on the computer.</para> - - <para>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.</para> - </sect3> - - <sect3 id="term-x"> - <title>X Terminals</title> - - <para>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.</para> - - <para>We introduce X terminals just for the sake of completeness. - However, this chapter does <emphasis>not</emphasis> cover setup, - configuration, or use of X terminals.</para> - </sect3> - </sect2> - - <sect2 id="term-cables-ports"> - <title>Cables and Ports</title> - - <para>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 <link - linkend="term-config">Configuration</link>.</para> - - <sect3 id="term-cables"> - <title>Cables</title> - - <para>Because terminals use serial ports, you need to use - serial—also known as RS-232C—cables to connect the - terminal to the FreeBSD system.</para> - - <para>There are a couple of kinds of serial cables. Which one - you'll use depends on the terminal you want to connect:</para> - - <itemizedlist> - <listitem> - <para>If you are connecting a personal computer to act as a - terminal, use a <link linkend="term-null">null-modem</link> - cable. A null-modem cable connects two computers or terminals - together.</para> - </listitem> - - <listitem> - <para>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 <link linkend="term-null">null-modem</link> cable. - If that does not work, then try a <link - linkend="term-std">standard</link> cable.</para> - </listitem> - </itemizedlist> - - <para>Also, the serial port on <emphasis>both</emphasis> the terminal - and your FreeBSD system must have connectors that will fit the cable - you are using.</para> - - <sect4 id="term-null"> - <title>Null-modem cables</title> - - <para>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.</para> - - <para>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.</para> - - <informaltable frame="none"> - <tgroup cols="5"> - <thead> - <row> - <entry>Signal</entry> - <entry>Pin #</entry> - <entry></entry> - <entry>Pin #</entry> - <entry>Signal</entry> - </row> - </thead> - - <tbody> - <row> - <entry>TxD</entry> - <entry>2</entry> - <entry>connects to</entry> - <entry>3</entry> - <entry>RxD</entry> - </row> - - <row> - <entry>RxD</entry> - <entry>3</entry> - <entry>connects to</entry> - <entry>2</entry> - <entry>TxD</entry> - </row> - - <row> - <entry>DTR</entry> - <entry>20</entry> - <entry>connects to</entry> - <entry>6</entry> - <entry>DSR</entry> - </row> - - <row> - <entry>DSR</entry> - <entry>6</entry> - <entry>connects to</entry> - <entry>20</entry> - <entry>DTR</entry> - </row> - - <row> - <entry>SG</entry> - <entry>7</entry> - <entry>connects to</entry> - <entry>7</entry> - <entry>SG</entry> - </row> - - <row> - <entry>DCD</entry> - <entry>8</entry> - <entry>connects to</entry> - <entry>4</entry> - <entry>RTS</entry> - </row> - - <row> - <entry>RTS</entry> - <entry>4</entry> - <entry></entry> - <entry>5</entry> - <entry>CTS</entry> - </row> - - <row> - <entry>CTS</entry> - <entry>5</entry> - <entry>connects to</entry> - <entry>8</entry> - <entry>DCD</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>For DCD to RTS, connect pins 4 to 5 internally in the - connector hood, and then to pin 8 in the remote - hood.</para> - </note> - </sect4> - - <sect4 id="term-std"> - <title>Standard RS-232C Cables</title> - - <para>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.</para> - </sect4> - </sect3> - - <sect3 id="term-ports"> - <title>Ports</title> - - <para>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.</para> - - <sect4 id="term-portkinds"> - <title>Kinds of Ports</title> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - </sect4> - - <sect4 id="term-portnames"> - <title>Port Names</title> - - <para>In FreeBSD, you access each serial port through an entry in - the <filename>/dev</filename> directory. There are two different - kinds of entries:</para> - - <itemizedlist> - <listitem> - <para>Callin ports are named - <filename>/dev/ttyd<replaceable>X</replaceable></filename> - where <replaceable>X</replaceable> 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.</para> - </listitem> - - <listitem> - <para>Callout ports are named - <filename>/dev/cuaa<replaceable>X</replaceable></filename>. - 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.</para> - </listitem> - </itemizedlist> - - <para>See the &man.sio.4; manual page for more information.</para> - - <para>If you have connected a terminal to the first serial port - (<devicename>COM1</devicename> in DOS parlance), then you want to - use <filename>/dev/ttyd0</filename> to refer to the terminal. If - it is on the second serial port (also known as - <devicename>COM2</devicename>), it is - <filename>/dev/ttyd1</filename>, and so forth.</para> - - <para>Note that you may have to configure your kernel to support - each serial port, especially if you have a multiport serial card. - See <link linkend="kernelconfig">Configuring the FreeBSD - Kernel</link> for more information.</para> - </sect4> - </sect3> - </sect2> - - <sect2 id="term-config"> - <title>Configuration</title> - - <para>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.</para> - - <para>In a nutshell, you need to tell the <command>init</command> - process, which is responsible for process control and initialization, - to start a <command>getty</command> process, which is responsible for - reading a login name and starting the <command>login</command> - program.</para> - - <para>To do so, you have to edit the <filename>/etc/ttys</filename> - file. First, use the <command>su</command> command to become root. - Then, make the following changes to - <filename>/etc/ttys</filename>:</para> - - <procedure> - <step> - <para>Add an line to <filename>/etc/ttys</filename> for the entry in - the <filename>/dev</filename> directory for the serial port if it - is not already there.</para> - </step> - - <step> - <para>Specify that <filename>/usr/libexec/getty</filename> be run on - the port, and specify the appropriate - <replaceable>getty</replaceable> type from the - <filename>/etc/gettytab</filename> file.</para> - </step> - - <step> - <para>Specify the default terminal type.</para> - </step> - - <step> - <para>Set the port to “on.”</para> - </step> - - <step> - <para>Specify whether the port should be - “secure.”</para> - </step> - - <step> - <para>Force <command>init</command> to reread the - <filename>/etc/ttys</filename> file.</para> - </step> - </procedure> - - <para>As an optional step, you may wish to create a custom - <replaceable>getty</replaceable> type for use in step 2 by making an - entry in <filename>/etc/gettytab</filename>. This document does - not explain how to do so; you are encouraged to see the - &man.gettytab.5; and the &man.getty.8; manual pages for more - information.</para> - - <para>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).</para> - - <para>For more information on the <filename>/etc/ttys</filename> - file, see the &man.ttys.5; manual page.</para> - - <sect3 id="term-etcttys"> - <title>Adding an Entry to <filename>/etc/ttys</filename></title> - - <para>First, you need to add an entry to the - <filename>/etc/ttys</filename> file, unless one is already - there.</para> - - <para>The <filename>/etc/ttys</filename> file lists all of the ports - on your FreeBSD system where you want to allow logins. For example, - the first virtual console <filename>ttyv0</filename> 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 <filename>/dev</filename> entry without the - <filename>/dev</filename> part.</para> - - <para>When you installed your FreeBSD system, the - <filename>/etc/ttys</filename> file included entries for the first - four serial ports: <filename>ttyd0</filename> through - <filename>ttyd3</filename>. If you are attaching a terminal on one - of those ports, you do not need to add an entry.</para> - - <para>In our example, we attached a Wyse-50 to the second serial port, - <filename>ttyd1</filename>, 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 <filename>/etc/ttys</filename> file after - we add the new entry:</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.9600" unknown off secure -ttyd5</programlisting> - </sect3> - - <sect3 id="term-getty"> - <title>Specifying the <replaceable>getty</replaceable> Type</title> - - <para>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 <filename>/usr/libexec/getty</filename>. It is what provides the - <prompt>login:</prompt> prompt.</para> - - <para>The program <command>getty</command> takes one (optional) - parameter on its command line, the <replaceable>getty</replaceable> - type. A <replaceable>getty</replaceable> type tells about - characteristics on the terminal line, like bps rate and parity. The - <command>getty</command> program reads these characteristics from - the file <filename>/etc/gettytab</filename>.</para> - - <para>The file <filename>/etc/gettytab</filename> contains lots of - entries for terminal lines both old and new. In almost all cases, - the entries that start with the text <literal>std</literal> will - work for hardwired terminals. These entries ignore parity. There is - a <literal>std</literal> entry for each bps rate from 110 to 115200. - Of course, you can add your own entries to this file. The manual - page &man.gettytab.5; provides more - information.</para> - - <para>When setting the <replaceable>getty</replaceable> type in the - <filename>/etc/ttys</filename> file, make sure that the - communications settings on the terminal match.</para> - - <para>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 <filename>/etc/ttys</filename> file so far (showing just - the two terminals in which we are interested):</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.38400" unknown off secure -ttyd5 "/usr/libexec/getty std.19200"</programlisting> - - <para>Note that the second field—where we specify what program - to run—appears in quotes. This is important, otherwise the - type argument to <command>getty</command> might be interpreted as - the next field.</para> - </sect3> - - <sect3 id="term-deftermtype"> - <title>Specifying the Default Terminal Type</title> - - <para>The third field in the <filename>/etc/ttys</filename> file lists - the default terminal type for the port. For dialup ports, you - typically put <literal>unknown</literal> or - <literal>dialup</literal> 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.</para> - - <para>Users will usually use the <command>tset</command> program in - their <filename>.login</filename> or <filename>.profile</filename> - files to check the terminal type and prompt for one if necessary. - By setting a terminal type in the <filename>/etc/ttys</filename> - file, users can forego such prompting.</para> - - <para>To find out what terminal types FreeBSD supports, see the - file <filename>/usr/share/misc/termcap</filename>. It lists - about 600 terminal types. You can add more if you wish. See - the &man.termcap.5; manual page for information.</para> - - <para>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 - <filename>/etc/ttys</filename> file:</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.38400" wy50 off secure -ttyd5 "/usr/libexec/getty std.19200" vt100</programlisting> - </sect3> - - <sect3 id="term-enable"> - <title>Enabling the Port</title> - - <para>The next field in <filename>/etc/ttys</filename>, the fourth - field, tells whether to enable the port. Putting - <literal>on</literal> here will have the <command>init</command> - process start the program in the second field, - <command>getty</command>, which will prompt for a login. If you put - <literal>off</literal> in the fourth field, there will be no - <command>getty</command>, and hence no logins on the port.</para> - - <para>So, naturally, you want an <literal>on</literal> in this field. - Here again is the <filename>/etc/ttys</filename> file. We have - turned each port <literal>on</literal>.</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.38400" wy50 on secure -ttyd5 "/usr/libexec/getty std.19200" vt100 on</programlisting> - </sect3> - - <sect3 id="term-secure"> - <title>Specifying Secure Ports</title> - - <para>We have arrived at the last field (well, almost: there is an - optional <literal>window</literal> specifier, but we will ignore - that). The last field tells whether the port is secure.</para> - - <para>What does “secure” mean?</para> - - <para>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.</para> - - <para>How do you use secure and insecure ports?</para> - - <para>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 <command>su</command> command.</para> - - <para>Because of this, you will have two records to help track down - possible compromises of root privileges: both the - <command>login</command> and the <command>su</command> command make - records in the system log (and logins are also recorded in the - <filename>wtmp</filename> file).</para> - - <para>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 <command>su</command> - command records.</para> - - <para>Which should you use?</para> - - <para>Just use “insecure.” Use “insecure” - <emphasis>even</emphasis> for terminals <emphasis>not</emphasis> in - public user areas or behind locked doors. It is quite easy to login - and use <command>su</command> if you need superuser - privileges.</para> - - <para>Here finally are the completed entries in the - <filename>/etc/ttys</filename> file, with comments added to describe - where the terminals are:</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure # Kitchen -ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure # Guest bathroom</programlisting> - </sect3> - - <sect3 id="term-hup"> - <title>Force <command>init</command> to Reread - <filename>/etc/ttys</filename></title> - - <para>When you boot FreeBSD, the first process, - <command>init</command>, will read the - <filename>/etc/ttys</filename> file and start the programs listed - for each enabled port to prompt for logins.</para> - - <para>After you edit <filename>/etc/ttys</filename>, you do not want - to have to reboot your system to get <command>init</command> to see - the changes. So, <command>init</command> will reread - <filename>/etc/ttys</filename> if it receives a SIGHUP (hangup) - signal.</para> - - <para>So, after you have saved your changes to - <filename>/etc/ttys</filename>, send <literal>SIGHUP</literal> to - <command>init</command> by typing:</para> - - <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen> - - <para>(The <command>init</command> process <emphasis>always</emphasis> - has process ID 1.)</para> - - <para>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!</para> - </sect3> - </sect2> - - <sect2 id="term-debug"> - <title>Debugging your connection</title> - - <para>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.</para> - - <variablelist> - <varlistentry> - <term>No login prompt appears</term> - - <listitem> - <para>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.</para> - - <para>Make sure the cable is connected firmly to both the terminal - and the FreeBSD computer. Make sure it is the right kind of - cable.</para> - - <para>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.</para> - - <para>Make sure that a <command>getty</command> process is running - and serving the terminal. Type <screen>&prompt.root; - <userinput>ps -axww|grep getty</userinput></screen> to get a - list of running <command>getty</command> processes. You should - see an entry for the terminal. For example, the display - - <screen>22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1</screen> - - shows that a <command>getty</command> is running on the second - serial port <literal>ttyd1</literal> and is using the - <literal>std.38400</literal> entry in - <filename>/etc/gettytab</filename>.</para> - - <para>If no <command>getty</command> process is running, make sure - you have enabled the port in <filename>/etc/ttys</filename>. - Make sure you have run <command>kill -HUP 1</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Garbage appears instead of a login prompt</term> - - <listitem> - <para>Make sure the terminal and FreeBSD agree on the bps rate and - parity settings. Check the getty processes to make sure the - correct <replaceable>getty</replaceable> type is in use. If - not, edit <filename>/etc/ttys</filename> and run <command>kill - -HUP 1</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Characters appear doubled; the password appears when - typed</term> - - <listitem> - <para>Switch the terminal (or the terminal emulation software) - from “half duplex” or “local echo” to - “full duplex.”</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="dialup"> - <title>Dialin Service</title> - - <para><emphasis>Contributed by &a.ghelmer;.</emphasis></para> - - <para>This document provides suggestions for configuring a FreeBSD system - to handle dialup modems. This document is written based on the author's - experience with FreeBSD versions 1.0, 1.1, and 1.1.5.1 (and experience - with dialup modems on other UNIX-like operating systems); however, this - document may not answer all of your questions or provide examples - specific enough to your environment. The author cannot be responsible if - you damage your system or lose data due to attempting to follow the - suggestions here.</para> - - <sect2 id="dialup-prereqs"> - <title>Prerequisites</title> - - <para>To begin with, the author assumes you have some basic knowledge of - FreeBSD. You need to have FreeBSD installed, know how to edit files - in a UNIX-like environment, and how to look up manual pages on the - system. As discussed below, you will need certain versions of - FreeBSD, and knowledge of some terminology & modem and - cabling.</para> - - <sect3> - <title>FreeBSD Version</title> - - <para>First, it is assumed that you are using FreeBSD version 1.1 or - higher (including versions 2.x). FreeBSD version 1.0 included two - different serial drivers, which complicates the situation. Also, - the serial device driver (<devicename>sio</devicename>) has improved - in every release of FreeBSD, so more recent versions of FreeBSD are - assumed to have better and more efficient drivers than earlier - versions.</para> - </sect3> - - <sect3> - <title>Terminology</title> - - <para>A quick rundown of terminology:</para> - - <variablelist> - <varlistentry> - <term>bps</term> - - <listitem> - <para>Bits per Second — the rate at which data is - transmitted</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>DTE</term> - - <listitem> - <para>Data Terminal Equipment — for example, your - computer</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>DCE</term> - - <listitem> - <para>Data Communications Equipment — your modem</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RS-232</term> - - <listitem> - <para>EIA standard for serial communications via hardware</para> - </listitem> - </varlistentry> - </variablelist> - - <para>If you need more information about these terms and data - communications in general, the author remembers reading that - <emphasis>The RS-232 Bible</emphasis> (anybody have an ISBN?) is a - good reference.</para> - - <para>When talking about communications data rates, the author does - not use the term “baud”. Baud refers to the number of - electrical state transitions that may be made in a period of time, - while “bps” (bits per second) is the - “correct” term to use (at least it does not seem to - bother the curmudgeons quite a much).</para> - </sect3> - - <sect3> - <title>External vs. Internal Modems</title> - - <para>External modems seem to be more convenient for dialup, because - external modems often can be semi-permanently configured via - parameters stored in non-volatile RAM and they usually provide - lighted indicators that display the state of important RS-232 - signals. Blinking lights impress visitors, but lights are also very - useful to see whether a modem is operating properly.</para> - - <para>Internal modems usually lack non-volatile RAM, so their - configuration may be limited only to setting DIP switches. If your - internal modem has any signal indicator lights, it is probably - difficult to view the lights when the system's cover is in - place.</para> - </sect3> - - <sect3> - <title>Modems and Cables</title> - - <para>A background knowledge of these items is assumed</para> - - <itemizedlist> - <listitem> - <para>You know how to connect your modem to your computer so that - the two can communicate (unless you have an internal modem, - which does not need such a cable)</para> - </listitem> - - <listitem> - <para>You are familiar with your modem's command set, or know - where to look up needed commands</para> - </listitem> - - <listitem> - <para>You know how to configure your modem (probably via a - terminal communications program) so you can set the non-volatile - RAM parameters</para> - </listitem> - </itemizedlist> - - <para>The first, connecting your modem, is usually simple — most - straight-through serial cables work without any problems. You need - to have a cable with appropriate connectors (DB-25 or DB-9, male or - female) on each end, and the cable must be a DCE-to-DTE cable with - these signals wired:</para> - - <itemizedlist> - <listitem> - <para>Transmitted Data (<acronym>SD</acronym>)</para> - </listitem> - - <listitem> - <para>Received Data (<acronym>RD</acronym>)</para> - </listitem> - - <listitem> - <para>Request to Send (<acronym>RTS</acronym>)</para> - </listitem> - - <listitem> - <para>Clear to Send (<acronym>CTS</acronym>)</para> - </listitem> - - <listitem> - <para>Data Set Ready (<acronym>DSR</acronym>)</para> - </listitem> - - <listitem> - <para>Data Terminal Ready (<acronym>DTR</acronym>)</para> - </listitem> - - <listitem> - <para>Carrier Detect (<acronym>CD</acronym>)</para> - </listitem> - - <listitem> - <para>Signal Ground (<acronym>SG</acronym>)</para> - </listitem> - </itemizedlist> - - <para>FreeBSD needs the <acronym>RTS</acronym> and - <acronym>CTS</acronym> signals for flow-control at speeds above - 2400bps, the <acronym>CD</acronym> signal to detect when a call has - been answered or the line has been hung up, and the - <acronym>DTR</acronym> signal to reset the modem after a session is - complete. Some cables are wired without all of the needed signals, - so if you have problems, such as a login session not going away when - the line hangs up, you may have a problem with your cable.</para> - - <para>The second prerequisite depends on the modem(s) you use. If you - do not know your modem's command set by heart, you will need to have - the modem's reference book or user's guide handy. Sample commands - for USR Sportster 14,400 external modems will be given, which you - may be able to use as a reference for your own modem's - commands.</para> - - <para>Lastly, you will need to know how to setup your modem so that it - will work well with FreeBSD. Like other UNIX-like operating - systems, FreeBSD uses the hardware signals to find out when a call - has been answered or a line has been hung up and to hangup and reset - the modem after a call. FreeBSD avoids sending commands to the - modem or watching for status reports from the modem. If you are - familiar with connecting modems to PC-based bulletin board systems, - this may seem awkward.</para> - </sect3> - - <sect3> - <title>Serial Interface Considerations</title> - - <para>FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based - EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and - 16450 devices have single-character buffers. The 16550 device - provides a 16-character buffer, which allows for better system - performance. (Bugs in plain 16550's prevent the use of the - 16-character buffer, so use 16550A's if possible). Because - single-character-buffer devices require more work by the operating - system than the 16-character-buffer devices, 16550A-based serial - interface cards are much preferred. If the system has many active - serial ports or will have a heavy load, 16550A-based cards are - better for low-error-rate communications.</para> - </sect3> - </sect2> - - <sect2> - <title>Quick Overview</title> - - <para>Here is the process that FreeBSD follows to accept dialup logins. - A <command>getty</command> process, spawned by - <command>init</command>, patiently waits to open the assigned serial - port (<filename>/dev/ttyd0</filename>, for our example). The command - <command>ps ax</command> might show this:</para> - - <screen> 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0</screen> - - <para>When a user dials the modem's line and the modems connect, the - <acronym>CD</acronym> line is asserted by the modem. The kernel - notices that carrier has been detected and completes - <command>getty</command>'s open of the port. <command>getty</command> - sends a <prompt>login:</prompt> prompt at the specified initial line - speed. <command>getty</command> watches to see if legitimate - characters are received, and, in a typical configuration, if it finds - junk (probably due to the modem's connection speed being different - than <command>getty</command>'s speed), <command>getty</command> tries - adjusting the line speeds until it receives reasonable - characters.</para> - - <para>We hope <command>getty</command> finds the correct speed and the - user sees a <prompt>login:</prompt> prompt. After the user enters - his/her login name, <command>getty</command> executes - <filename>/usr/bin/login</filename>, which completes the login by - asking for the user's password and then starting the user's - shell.</para> - - <para>Let's dive into the configuration...</para> - </sect2> - - <sect2> - <title>Kernel Configuration</title> - - <para>FreeBSD kernels typically come prepared to search for four serial - ports, known in the PC-DOS world as <devicename>COM1:</devicename>, - <devicename>COM2:</devicename>, <devicename>COM3:</devicename>, and - <devicename>COM4:</devicename>. FreeBSD can presently also handle - “dumb” multiport serial interface cards, such as the Boca - Board 1008 and 2016 (please see the manual page &man.sio.4; for kernel - configuration information if you have a multiport serial card). The - default kernel only looks for the standard COM ports, though.</para> - - <para>To see if your kernel recognizes any of your serial ports, watch - for messages while the kernel is booting, or use the - <command>/sbin/dmesg</command> command to replay the kernel's boot - messages. In particular, look for messages that start with the - characters <literal>sio</literal>. Hint: to view just the messages - that have the word <literal>sio</literal>, use the command:</para> - - <screen>&prompt.root; <userinput>/sbin/dmesg | grep 'sio'</userinput></screen> - - <para>For example, on a system with four serial ports, these are the - serial-port specific kernel boot messages:</para> - - <screen>sio0 at 0x3f8-0x3ff irq 4 on isa -sio0: type 16550A -sio1 at 0x2f8-0x2ff irq 3 on isa -sio1: type 16550A -sio2 at 0x3e8-0x3ef irq 5 on isa -sio2: type 16550A -sio3 at 0x2e8-0x2ef irq 9 on isa -sio3: type 16550A</screen> - - <para>If your kernel does not recognize all of your serial ports, you - will probably need to configure a custom FreeBSD kernel for your - system.</para> - - <para>Please see the BSD System Manager's Manual chapter on - “Building Berkeley Kernels with Config” [the source for - which is in <filename>/usr/src/share/doc/smm</filename>] and - “FreeBSD Configuration Options” [in - <filename>/sys/conf/options</filename> and in - <filename>/sys/<replaceable>arch</replaceable>/conf/options.<replaceable>arch</replaceable></filename>, - with <emphasis>arch</emphasis> for example being - <filename>i386</filename>] for more information on configuring and - building kernels. You may have to unpack the kernel source - distribution if have not installed the system sources already - (<filename>srcdist/srcsys.??</filename> in FreeBSD 1.1, - <filename>srcdist/sys.??</filename> in FreeBSD 1.1.5.1, or the entire - source distribution in FreeBSD 2.0) to be able to configure and build - kernels.</para> - - <para>Create a kernel configuration file for your system (if you have - not already) by <command>cd</command>ing to - <filename>/sys/i386/conf</filename>. Then, if you are creating a new - custom configuration file, copy the file - <filename>GENERICAH</filename> (or <filename>GENERICBT</filename>, if - you have a BusTek SCSI controller on FreeBSD 1.x) to - <filename>YOURSYS</filename>, where <filename>YOURSYS</filename> is - the name of your system, but in upper-case letters. Edit the file, - and change the device lines:</para> - - <programlisting> -device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr -device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr -device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr -device sio3 at isa? port "IO_COM4" tty irq 9 vector siointr</programlisting> - - <para>You can comment-out or completely remove lines for devices you do - not have. If you have a multiport serial board, such as the Boca - Board BB2016, please see the &man.sio.4; man page for complete - information on how to write configuration lines for multiport boards. - Be careful if you are using a configuration file that was previously - used for a different version of FreeBSD because the device flags have - changed between versions.</para> - - <note> - <para><literal>port "IO_COM1"</literal> is a substitution for - <literal>port 0x3f8</literal>, <literal>IO_COM2</literal> is - <literal>0x2f8</literal>, <literal>IO_COM3</literal> is - <literal>0x3e8</literal>, and <literal>IO_COM4</literal> is - <literal>0x2e8</literal>, which are fairly common port addresses for - their respective serial ports; interrupts 4, 3, 5, and 9 are fairly - common interrupt request lines. Also note that regular serial ports - <emphasis>cannot</emphasis> share interrupts on ISA-bus PCs - (multiport boards have on-board electronics that allow all the - 16550A's on the board to share one or two interrupt request - lines).</para> - </note> - - <para>When you are finished adjusting the kernel configuration file, use - the program <command>config</command> as documented in “Building - Berkeley Kernels with Config” and the - &man.config.8; manual page to prepare a kernel building directory, - then build, install, and test the new kernel.</para> - </sect2> - - <sect2> - <title>Device Special Files</title> - - <para>Most devices in the kernel are accessed through “device - special files”, which are located in the - <filename>/dev</filename> directory. The <devicename>sio</devicename> - devices are accessed through the - <filename>/dev/ttyd<replaceable>?</replaceable></filename> (dial-in) - and <filename>/dev/cua0<replaceable>?</replaceable></filename> - (call-out) devices. On FreeBSD version 1.1.5 and higher, there are - also initialization devices - (<filename>/dev/ttyid<replaceable>?</replaceable></filename> and - <filename>/dev/cuai0<replaceable>?</replaceable></filename>) and - locking devices - (<filename>/dev/ttyld<replaceable>?</replaceable></filename> and - <filename>/dev/cual0<replaceable>?</replaceable></filename>). The - initialization devices are used to initialize communications port - parameters each time a port is opened, such as - <literal>crtscts</literal> for modems which use - <literal>CTS/RTS</literal> signaling for flow control. The locking - devices are used to lock flags on ports to prevent users or programs - changing certain parameters; see the manual pages &man.termios.4;, - &man.sio.4;, and &man.stty.1; for - information on the terminal settings, locking & initializing - devices, and setting terminal options, respectively.</para> - - <sect3> - <title>Making Device Special Files</title> - - <para>A shell script called <command>MAKEDEV</command> in the - <filename>/dev</filename> directory manages the device special - files. (The manual page for &man.MAKEDEV.8; on FreeBSD 1.1.5 is - fairly bogus in its discussion of <acronym>COM</acronym> ports, so - ignore it.) To use <command>MAKEDEV</command> to make dialup device - special files for <devicename>COM1:</devicename> (port 0), - <command>cd</command> to <filename>/dev</filename> and issue the - command <command>MAKEDEV ttyd0</command>. Likewise, to make dialup - device special files for <devicename>COM2:</devicename> (port 1), - use <command>MAKEDEV ttyd1</command>.</para> - - <para><command>MAKEDEV</command> not only creates the - <filename>/dev/ttyd<replaceable>?</replaceable></filename> device - special files, but also creates the - <filename>/dev/cua0<replaceable>?</replaceable></filename> (and all - of the initializing and locking special files under FreeBSD 1.1.5 - and up) and removes the hardwired terminal special file - <filename>/dev/tty0<replaceable>?</replaceable></filename>, if it - exists.</para> - - <para>After making new device special files, be sure to check the - permissions on the files (especially the - <filename>/dev/cua*</filename> files) to make sure that only users - who should have access to those device special files can read & - write on them — you probably do not want to allow your average - user to use your modems to dialout. The default permissions on the - <filename>/dev/cua*</filename> files should be sufficient:</para> - - <screen>crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cua01 -crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuai01 -crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cual01</screen> - - <para>These permissions allow the user <username>uucp</username> and - users in the group <username>dialer</username> to use the call-out - devices.</para> - </sect3> - </sect2> - - <sect2> - <title>Configuration Files</title> - - <para>There are three system configuration files in the - <filename>/etc</filename> directory that you will probably need to - edit to allow dialup access to your FreeBSD system. The first, - <filename>/etc/gettytab</filename>, contains configuration information - for the <filename>/usr/libexec/getty</filename> daemon. Second, - <filename>/etc/ttys</filename> holds information that tells - <filename>/sbin/init</filename> what <filename>tty</filename> devices - should have <command>getty</command> processes running on them. - Lastly, you can place port initialization commands in the - <filename>/etc/rc.serial</filename> script if you have FreeBSD 1.1.5.1 - or higher; otherwise, you can initialize ports in the - <filename>/etc/rc.local</filename> script.</para> - - <para>There are two schools of thought regarding dialup modems on UNIX. - One group likes to configure their modems and system so that no matter - at what speed a remote user dials in, the local computer-to-modem - RS-232 interface runs at a locked speed. The benefit of this - configuration is that the remote user always sees a system login - prompt immediately. The downside is that the system does not know - what a user's true data rate is, so full-screen programs like Emacs - will not adjust their screen-painting methods to make their response - better for slower connections.</para> - - <para>The other school configures their modems' RS-232 interface to vary - its speed based on the remote user's connection speed. For example, - V.32bis (14.4 Kbps) connections to the modem might make the modem run - its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the - modem's RS-232 interface run at 2400 bps. Because - <command>getty</command> does not understand any particular modem's - connection speed reporting, <command>getty</command> gives a - <prompt>login:</prompt> message at an initial speed and watches the - characters that come back in response. If the user sees junk, it is - assumed that they know they should press the - <literal><Enter></literal> key until they see a recognizable - prompt. If the data rates do not match, <command>getty</command> sees - anything the user types as “junk”, tries going to the next - speed and gives the <prompt>login:</prompt> prompt again. This - procedure can continue ad nauseum, but normally only takes a keystroke - or two before the user sees a good prompt. Obviously, this login - sequence does not look as clean as the former - “locked-speed” method, but a user on a low-speed - connection should receive better interactive response from full-screen - programs.</para> - - <para>The author will try to give balanced configuration information, - but is biased towards having the modem's data rate follow the - connection rate.</para> - - <sect3> - <title><filename>/etc/gettytab</filename></title> - - <para><filename>/etc/gettytab</filename> is a &man.termcap.5;-style - file of configuration information for &man.getty.8;. Please see the - &man.gettytab.5; manual page for complete information on the - format of the file and the list of capabilities.</para> - - <sect4> - <title>Locked-Speed Config</title> - - <para>If you are locking your modem's data communications rate at a - particular speed, you probably will not need to make any changes - to <filename>/etc/gettytab</filename>.</para> - </sect4> - - <sect4> - <title>Matching-Speed Config</title> - - <para>You will need to setup an entry in - <filename>/etc/gettytab</filename> to give - <command>getty</command> information about the speeds you wish to - use for your modem. If you have a 2400 bps modem, you can - probably use the existing <literal>D2400</literal> entry. This - entry already exists in the FreeBSD 1.1.5.1 - <filename>gettytab</filename> file, so you do not need to add it - unless it is missing under your version of FreeBSD:</para> - - <programlisting> -# -# Fast dialup terminals, 2400/1200/300 rotary (can start either way) -# -D2400|d2400|Fast-Dial-2400:\ - :nx=D1200:tc=2400-baud: -3|D1200|Fast-Dial-1200:\ - :nx=D300:tc=1200-baud: -5|D300|Fast-Dial-300:\ - :nx=D2400:tc=300-baud:</programlisting> - - <para>If you have a higher speed modem, you will probably need to - add an entry in <filename>/etc/gettytab</filename>; here is an - entry you could use for a 14.4 Kbps modem with a top interface - speed of 19.2 Kbps:</para> - - <programlisting> -# -# Additions for a V.32bis Modem -# -um|V300|High Speed Modem at 300,8-bit:\ - :nx=V19200:tc=std.300: -un|V1200|High Speed Modem at 1200,8-bit:\ - :nx=V300:tc=std.1200: -uo|V2400|High Speed Modem at 2400,8-bit:\ - :nx=V1200:tc=std.2400: -up|V9600|High Speed Modem at 9600,8-bit:\ - :nx=V2400:tc=std.9600: -uq|V19200|High Speed Modem at 19200,8-bit:\ - :nx=V9600:tc=std.19200:</programlisting> - - <para>On FreeBSD 1.1.5 and later, this will result in 8-bit, no - parity connections. Under FreeBSD 1.1, add - <literal>:np:</literal> parameters to the - <literal>std.<replaceable>xxx</replaceable></literal> entries at - the top of the file for 8 bits, no parity; otherwise, the default - is 7 bits, even parity.</para> - - <para>The example above starts the communications rate at 19.2 Kbps - (for a V.32bis connection), then cycles through 9600 bps (for - V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. - Communications rate cycling is implemented with the - <literal>nx=</literal> (“next table”) capability. - Each of the lines uses a <literal>tc=</literal> (“table - continuation”) entry to pick up the rest of the - “standard” settings for a particular data rate.</para> - - <para>If you have a 28.8 Kbps modem and/or you want to take - advantage of compression on a 14.4 Kbps modem, you need to use a - higher communications rate than 19.2 Kbps. Here is an example of - a <filename>gettytab</filename> entry starting a 57.6 Kbps:</para> - - <programlisting> -# -# Additions for a V.32bis or V.34 Modem -# Starting at 57.6 Kbps -# -vm|VH300|Very High Speed Modem at 300,8-bit:\ - :nx=VH57600:tc=std.300: -vn|VH1200|Very High Speed Modem at 1200,8-bit:\ - :nx=VH300:tc=std.1200: -vo|VH2400|Very High Speed Modem at 2400,8-bit:\ - :nx=VH1200:tc=std.2400: -vp|VH9600|Very High Speed Modem at 9600,8-bit:\ - :nx=VH2400:tc=std.9600: -vq|VH57600|Very High Speed Modem at 57600,8-bit:\ - :nx=VH9600:tc=std.57600:</programlisting> - - <para>If you have a slow CPU or a heavily loaded system and you do - not have 16550A-based serial ports, you may receive sio - “silo” errors at 57.6 Kbps.</para> - </sect4> - </sect3> - - <sect3 id="dialup-ttys"> - <title><filename>/etc/ttys</filename></title> - - <para><filename>/etc/ttys</filename> is the list of - <filename>ttys</filename> for <command>init</command> to monitor. - <filename>/etc/ttys</filename> also provides security information to - <command>login</command> (user <username>root</username> may only - login on ttys marked <literal>secure</literal>). See the manual - page for - &man.ttys.5; for more information.</para> - - <para>You will need to either modify existing lines in - <filename>/etc/ttys</filename> or add new lines to make - <command>init</command> run <command>getty</command> processes - automatically on your new dialup ports. The general format of the - line will be the same, whether you are using a locked-speed or - matching-speed configuration:</para> - - <programlisting> -ttyd0 "/usr/libexec/getty xxx" dialup on</programlisting> - - <para>The first item in the above line is the device special file for - this entry — <literal>ttyd0</literal> means - <filename>/dev/ttyd0</filename> is the file that this - <command>getty</command> will be watching. The second item, - <literal>"/usr/libexec/getty - <replaceable>xxx</replaceable>"</literal> - (<replaceable>xxx</replaceable> will be replaced by the initial - <filename>gettytab</filename> capability) is the process - <command>init</command> will run on the device. The third item, - <literal>dialup</literal>, is the default terminal type. The fourth - parameter, <literal>on</literal>, indicates to - <command>init</command> that the line is operational. There can be - a fifth parameter, <literal>secure</literal>, but it should only be - used for terminals which are physically secure (such as the system - console).</para> - - <para>The default terminal type (<literal>dialup</literal> in the - example above) may depend on local preferences. - <literal>dialup</literal> is the traditional default terminal type - on dialup lines so that users may customize their login scripts to - notice when the terminal is <literal>dialup</literal> and - automatically adjust their terminal type. However, the author finds - it easier at his site to specify <literal>vt102</literal> as the - default terminal type, since the users just use VT102 emulation on - their remote systems.</para> - - <para>After you have made changes to <filename>/etc/ttys</filename>, - you may send the <command>init</command> process a - <acronym>HUP</acronym> signal to re-read the file. You can use the - command <screen>&prompt.root; <userinput>kill -1 - 1</userinput></screen> to send the signal. If this is your - first time setting up the system, though, you may want to wait until - your modem(s) are properly configured and connected before signaling - <command>init</command>.</para> - - <sect4> - <title>Locked-Speed Config</title> - - <para>For a locked-speed configuration, your - <filename>ttys</filename> entry needs to have a fixed-speed entry - provided to <command>getty</command>. For a modem whose port - speed is locked at 19.2 Kbps, the <filename>ttys</filename> entry - might look like this:</para> - - <programlisting> -ttyd0 "/usr/libexec/getty std.19200" dialup on</programlisting> - - <para>If your modem is locked at a different data rate, substitute - the appropriate name for the - <literal>std.<replaceable>speed</replaceable></literal> entry for - <literal>std.19200</literal> from - <filename>/etc/gettytab</filename> for your modem's data - rate.</para> - </sect4> - - <sect4> - <title>Matching-Speed Config</title> - - <para>In a matching-speed configuration, your - <filename>ttys</filename> entry needs to reference the appropriate - beginning “auto-baud” (sic) entry in - <filename>/etc/gettytab</filename>. For example, if you added the - above suggested entry for a matching-speed modem that starts at - 19.2 Kbps (the <filename>gettytab</filename> entry containing the - <literal>V19200</literal> starting point), your - <filename>ttys</filename> entry might look like this:</para> - - <programlisting> -ttyd0 "/usr/libexec/getty V19200" dialup on</programlisting> - </sect4> - </sect3> - - <sect3> - <title><filename>/etc/rc.serial</filename> or - <filename>/etc/rc.local</filename></title> - - <para>High-speed modems, like V.32, V.32bis, and V.34 modems, need to - use hardware (<filename>RTS/CTS</filename>) flow control. You can - add <command>stty</command> commands to - <filename>/etc/rc.serial</filename> on FreeBSD 1.1.5.1 and up, or - <filename>/etc/rc.local</filename> on FreeBSD 1.1, to set the - hardware flow control flag in the FreeBSD kernel for the modem - ports.</para> - - <para>For example, on a sample FreeBSD 1.1.5.1 system, - <filename>/etc/rc.serial</filename> reads:</para> - - <programlisting> -#!/bin/sh -# -# Serial port initial configuration - -stty -f /dev/ttyid1 crtscts -stty -f /dev/cuai01 crtscts</programlisting> - - <para>This sets the <literal>termios</literal> flag - <literal>crtscts</literal> on serial port #1's - (<devicename>COM2:</devicename>) dialin and dialout initialization - devices.</para> - - <para>On an old FreeBSD 1.1 system, these entries were added to - <filename>/etc/rc.local</filename> to set the - <literal>crtscts</literal> flag on the devices:</para> - - <programlisting> -# Set serial ports to use RTS/CTS flow control -stty -f /dev/ttyd0 crtscts -stty -f /dev/ttyd1 crtscts -stty -f /dev/ttyd2 crtscts -stty -f /dev/ttyd3 crtscts</programlisting> - - <para>Since there is no initialization device special file on FreeBSD - 1.1, one has to just set the flags on the sole device special file - and hope the flags are not cleared by a miscreant.</para> - </sect3> - </sect2> - - <sect2> - <title>Modem Settings</title> - - <para>If you have a modem whose parameters may be permanently set in - non-volatile RAM, you will need to use a terminal program (such as - Telix under PC-DOS or <command>tip</command> under FreeBSD) to set the - parameters. Connect to the modem using the same communications speed - as the initial speed <command>getty</command> will use and configure - the modem's non-volatile RAM to match these requirements:</para> - - <itemizedlist> - <listitem> - <para><acronym>CD</acronym> asserted when connected</para> - </listitem> - - <listitem> - <para><acronym>DTR</acronym> asserted for operation; dropping DTR - hangs up line & resets modem</para> - </listitem> - - <listitem> - <para><acronym>CTS</acronym> transmitted data flow control</para> - </listitem> - - <listitem> - <para>Disable <acronym>XON/XOFF</acronym> flow control</para> - </listitem> - - <listitem> - <para><acronym>RTS</acronym> received data flow control</para> - </listitem> - - <listitem> - <para>Quiet mode (no result codes)</para> - </listitem> - - <listitem> - <para>No command echo</para> - </listitem> - </itemizedlist> - - <para>Please read the documentation for your modem to find out what - commands and/or DIP switch settings you need to give it.</para> - - <para>For example, to set the above parameters on a USRobotics - Sportster 14,400 external modem, one could give these commands to - the modem:</para> - - <programlisting> -ATZ -AT&C1&D2&H1&I0&R2&W</programlisting> - - <para>You might also want to take this opportunity to adjust other - settings in the modem, such as whether it will use V.42bis and/or MNP5 - compression.</para> - - <para>The USR Sportster 14,400 external modem also has some DIP switches - that need to be set; for other modems, perhaps you can use these - settings as an example:</para> - - <itemizedlist> - <listitem> - <para>Switch 1: UP — DTR Normal</para> - </listitem> - - <listitem> - <para>Switch 2: Do not care (Verbal Result Codes/Numeric Result - Codes)</para> - </listitem> - - <listitem> - <para>Switch 3: UP — Suppress Result Codes</para> - </listitem> - - <listitem> - <para>Switch 4: DOWN — No echo, offline commands</para> - </listitem> - - <listitem> - <para>Switch 5: UP — Auto Answer</para> - </listitem> - - <listitem> - <para>Switch 6: UP — Carrier Detect Normal</para> - </listitem> - - <listitem> - <para>Switch 7: UP — Load NVRAM Defaults</para> - </listitem> - - <listitem> - <para>Switch 8: Do not care (Smart Mode/Dumb Mode)</para> - </listitem> - </itemizedlist> - - <para>Result codes should be disabled/suppressed for dialup modems to - avoid problems that can occur if <command>getty</command> mistakenly - gives a <prompt>login:</prompt> prompt to a modem that is in command - mode and the modem echoes the command or returns a result code. I - have heard this sequence can result in a extended, silly conversation - between <command>getty</command> and the modem.</para> - - <sect3> - <title>Locked-speed Config</title> - - <para>For a locked-speed configuration, you will need to configure the - modem to maintain a constant modem-to-computer data rate independent - of the communications rate. On a USR Sportster 14,400 external - modem, these commands will lock the modem-to-computer data rate at - the speed used to issue the commands:</para> - - <programlisting> -ATZ -AT&B1&W</programlisting> - </sect3> - - <sect3> - <title>Matching-speed Config</title> - - <para>For a variable-speed configuration, you will need to configure - your modem to adjust its serial port data rate to match the incoming - call rate. On a USR Sportster 14,400 external modem, these commands - will lock the modem's error-corrected data rate to the speed used to - issue the commands, but allow the serial port rate to vary for - non-error-corrected connections:</para> - - <programlisting> -ATZ -AT&B2&W</programlisting> - </sect3> - - <sect3> - <title>Checking the Modem's Configuration</title> - - <para>Most high-speed modems provide commands to view the modem's - current operating parameters in a somewhat human-readable fashion. - On the USR Sportster 14,400 external modems, the command - <command>ATI5</command> displays the settings that are stored in the - non-volatile RAM. To see the true operating parameters of the modem - (as influenced by the USR's DIP switch settings), use the commands - <command>ATZ</command> and then <command>ATI4</command>.</para> - - <para>If you have a different brand of modem, check your modem's - manual to see how to double-check your modem's configuration - parameters.</para> - </sect3> - </sect2> - - <sect2> - <title>Troubleshooting</title> - - <para>Here are a few steps you can follow to check out the dialup modem - on your system.</para> - - <sect3> - <title>Checking out the FreeBSD system</title> - - <para>Hook up your modem to your FreeBSD system, boot the system, and, - if your modem has status indication lights, watch to see whether the - modem's <acronym>DTR</acronym> indicator lights when the - <prompt>login:</prompt> prompt appears on the system's console - — if it lights up, that should mean that FreeBSD has started a - <command>getty</command> process on the appropriate communications - port and is waiting for the modem to accept a call.</para> - - <para>If the <acronym>DTR</acronym> indicator doesn't light, login to - the FreeBSD system through the console and issue a <command>ps - ax</command> to see if FreeBSD is trying to run a - <command>getty</command> process on the correct port. You should see - a lines like this among the processes displayed:</para> - - <screen> 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0 - 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1</screen> - - <para>If you see something different, like this:</para> - - <screen> 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0</screen> - - <para>and the modem has not accepted a call yet, this means that - <command>getty</command> has completed its open on the - communications port. This could indicate a problem with the cabling - or a mis-configured modem, because <command>getty</command> should - not be able to open the communications port until - <acronym>CD</acronym> (carrier detect) has been asserted by the - modem.</para> - - <para>If you do not see any <command>getty</command> processes waiting - to open the desired - <filename>ttyd<replaceable>?</replaceable></filename> port, - double-check your entries in <filename>/etc/ttys</filename> to see - if there are any mistakes there. Also, check the log file - <filename>/var/log/messages</filename> to see if there are any log - messages from <command>init</command> or <command>getty</command> - regarding any problems. If there are any messages, triple-check the - configuration files <filename>/etc/ttys</filename> and - <filename>/etc/gettytab</filename>, as well as the appropriate - device special files <filename>/dev/ttyd?</filename>, for any - mistakes, missing entries, or missing device special files.</para> - </sect3> - - <sect3> - <title>Try Dialing In</title> - - <para>Try dialing into the system; be sure to use 8 bits, no parity, 1 - stop bit on the remote system. If you do not get a prompt right - away, or get garbage, try pressing <literal><Enter></literal> - about once per second. If you still do not see a - <prompt>login:</prompt> prompt after a while, try sending a - <command>BREAK</command>. If you are using a high-speed modem to do - the dialing, try dialing again after locking the dialing modem's - interface speed (via <command>AT&B1</command> on a USR - Sportster, for example).</para> - - <para>If you still cannot get a <prompt>login:</prompt> prompt, check - <filename>/etc/gettytab</filename> again and double-check - that</para> - - <itemizedlist> - <listitem> - <para>The initial capability name specified in - <filename>/etc/ttys</filename> for the line matches a name of a - capability in <filename>/etc/gettytab</filename></para> - </listitem> - - <listitem> - <para>Each <literal>nx=</literal> entry matches another - <filename>gettytab</filename> capability name</para> - </listitem> - - <listitem> - <para>Each <literal>tc=</literal> entry matches another - <filename>gettytab</filename> capability name</para> - </listitem> - </itemizedlist> - - <para>If you dial but the modem on the FreeBSD system will not answer, - make sure that the modem is configured to answer the phone when - <acronym>DTR</acronym> is asserted. If the modem seems to be - configured correctly, verify that the <acronym>DTR</acronym> line is - asserted by checking the modem's indicator lights (if it has - any).</para> - - <para>If you have gone over everything several times and it still does - not work, take a break and come back to it later. If it still does - not work, perhaps you can send an electronic mail message to the - &a.questions;describing your modem and your problem, and the good - folks on the list will try to help.</para> - </sect3> - </sect2> - - <sect2> - <title>Acknowledgments</title> - - <para>Thanks to these people for comments and advice:</para> - - <variablelist> - <varlistentry> - <term>&a.kelly;</term> - - <listitem> - <para>for a number of good suggestions</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="dialout"> - <title>Dialout Service</title> - - <para><emphasis>Information integrated from FAQ.</emphasis></para> - - <para>The following are tips to getting your host to be able to connect - over the modem to another computer. This is appropriate for - establishing a terminal session with a remote host.</para> - - <para>This is useful to log onto a BBS.</para> - - <para>This kind of connection can be extremely helpful to get a file on - the Internet if you have problems with PPP. If you need to ftp - something and PPP is broken, use the terminal session to ftp it. Then - use zmodem to transfer it to your machine.</para> - - <sect2> - <title>Why cannot I run <command>tip</command> or - <command>cu</command>?</title> - - <para>On your system, the programs <command>tip</command> and - <command>cu</command> are probably executable only by - <username>uucp</username> and group <username>dialer</username>. You - can use the group <username>dialer</username> to control who has - access to your modem or remote systems. Just add yourself to group - dialer.</para> - - <para>Alternatively, you can let everyone on your system run - <command>tip</command> and <command>cu</command> by typing:</para> - - <screen>&prompt.root; <userinput>chmod 4511 /usr/bin/tip</userinput></screen> - - <para>You do not have to run this command for <command>cu</command>, - since <command>cu</command> is just a hard link to - <command>tip</command>.</para> - </sect2> - - <sect2> - <title>My stock Hayes modem is not supported, what can I do?</title> - - <para>Actually, the man page for <command>tip</command> is out of date. - There is a generic Hayes dialer already built in. Just use - <literal>at=hayes</literal> in your <filename>/etc/remote</filename> - file.</para> - - <para>The Hayes driver is not smart enough to recognize some of the - advanced features of newer modems—messages like - <literal>BUSY</literal>, <literal>NO DIALTONE</literal>, or - <literal>CONNECT 115200</literal> will just confuse it. You should - turn those messages off when you use <command>tip</command> (using - <command>ATX0&W</command>).</para> - - <para>Also, the dial timeout for <command>tip</command> is 60 seconds. - Your modem should use something less, or else tip will think there is - a communication problem. Try <command>ATS7=45&W</command>.</para> - - <para>Actually, as shipped <command>tip</command> does not yet support - it fully. The solution is to edit the file - <filename>tipconf.h</filename> in the directory - <filename>/usr/src/usr.bin/tip/tip</filename> Obviously you need the - source distribution to do this.</para> - - <para>Edit the line <literal>#define HAYES 0</literal> to - <literal>#define HAYES 1</literal>. Then <command>make</command> and - <command>make install</command>. Everything works nicely after - that.</para> - </sect2> - - <sect2 id="direct-at"> - <title>How am I expected to enter these AT commands?</title> - - <para>Make what is called a “direct” entry in your - <filename>/etc/remote</filename> file. For example, if your modem is - hooked up to the first serial port, <filename>/dev/cuaa0</filename>, - then put in the following line:</para> - - <programlisting> -cuaa0:dv=/dev/cuaa0:br#19200:pa=none</programlisting> - - <para>Use the highest bps rate your modem supports in the br capability. - Then, type <command>tip cuaa0</command> and you will be connected to - your modem.</para> - - <para>If there is no <filename>/dev/cuaa0</filename> on your system, do - this:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>MAKEDEV cuaa0</userinput></screen> - - <para>Or use cu as root with the following command:</para> - - <screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen> - - <para><replaceable>line</replaceable> is the serial port - (e.g.<filename>/dev/cuaa0</filename>) and - <replaceable>speed</replaceable> is the speed - (e.g.<literal>57600</literal>). When you are done entering the AT - commands hit <command>~.</command> to exit.</para> - </sect2> - - <sect2> - <title>The <literal>@</literal> sign for the pn capability does not - work!</title> - - <para>The <literal>@</literal> sign in the phone number capability tells - tip to look in <filename>/etc/phones</filename> for a phone number. - But the <literal>@</literal> sign is also a special character in - capability files like <filename>/etc/remote</filename>. Escape it - with a backslash:</para> - - <programlisting> -pn=\@</programlisting> - </sect2> - - <sect2> - <title>How can I dial a phone number on the command line?</title> - - <para>Put what is called a “generic” entry in your - <filename>/etc/remote</filename> file. For example:</para> - - <programlisting> -tip115200|Dial any phone number at 115200 bps:\ - :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du: -tip57600|Dial any phone number at 57600 bps:\ - :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:</programlisting> - - <para>Then you can things like:</para> - - <screen>&prompt.root; <userinput>tip -115200 5551234</userinput></screen> - - <para>If you prefer <command>cu</command> over <command>tip</command>, - use a generic cu entry:</para> - - <programlisting> -cu115200|Use cu to dial any number at 115200bps:\ - :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:</programlisting> - - <para>and type:</para> - - <screen>&prompt.root; <userinput>cu 5551234 -s 115200</userinput></screen> - </sect2> - - <sect2> - <title>Do I have to type in the bps rate every time I do that?</title> - - <para>Put in an entry for <literal>tip1200</literal> or - <literal>cu1200</literal>, but go ahead and use whatever bps rate is - appropriate with the br capability. <command>tip</command> thinks a - good default is 1200 bps which is why it looks for a - <literal>tip1200</literal> entry. You do not have to use 1200 bps, - though.</para> - </sect2> - - <sect2> - <title>I access a number of hosts through a terminal server.</title> - - <para>Rather than waiting until you are connected and typing - <command>CONNECT <host></command> each time, use tip's - <literal>cm</literal> capability. For example, these entries in - <filename>/etc/remote</filename>:</para> - - <programlisting> -pain|pain.deep13.com|Forrester's machine:\ - :cm=CONNECT pain\n:tc=deep13: -muffin|muffin.deep13.com|Frank's machine:\ - :cm=CONNECT muffin\n:tc=deep13: -deep13:Gizmonics Institute terminal server:\ - :dv=/dev/cua02:br#38400:at=hayes:du:pa=none:pn=5551234:</programlisting> - - <para>will let you type <command>tip pain</command> or <command>tip - muffin</command> to connect to the hosts pain or muffin; and - <command>tip deep13</command> to get to the terminal server.</para> - </sect2> - - <sect2> - <title>Can tip try more than one line for each site?</title> - - <para>This is often a problem where a university has several modem lines - and several thousand students trying to use them...</para> - - <para>Make an entry for your university in - <filename>/etc/remote</filename> and use <literal>@</literal> for the - <literal>pn</literal> capability:</para> - - <programlisting> -big-university:\ - :pn=\@:tc=dialout -dialout:\ - :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:</programlisting> - - <para>Then, list the phone numbers for the university in - <filename>/etc/phones</filename>:</para> - - <programlisting> -big-university 5551111 -big-university 5551112 -big-university 5551113 -big-university 5551114</programlisting> - - <para><command>tip</command> will try each one in the listed order, then - give up. If you want to keep retrying, run <command>tip</command> in - a while loop.</para> - </sect2> - - <sect2> - <title>Why do I have to hit CTRL+P twice to send CTRL+P once?</title> - - <para>CTRL+P is the default “force” character, used to tell - <command>tip</command> that the next character is literal data. You - can set the force character to any other character with the - <command>~s</command> escape, which means “set a - variable.”</para> - - <para>Type - <command>~sforce=<replaceable>single-char</replaceable></command> - followed by a newline. <replaceable>single-char</replaceable> is any - single character. If you leave out - <replaceable>single-char</replaceable>, then the force character is - the nul character, which you can get by typing CTRL+2 or CTRL+SPACE. - A pretty good value for <replaceable>single-char</replaceable> is - SHIFT+CTRL+6, which I have seen only used on some terminal - servers.</para> - - <para>You can have the force character be whatever you want by - specifying the following in your <filename>$HOME/.tiprc</filename> - file:</para> - - <programlisting> -force=<single-char></programlisting> - </sect2> - - <sect2> - <title>Suddenly everything I type is in UPPER CASE??</title> - - <para>You must have pressed CTRL+A, <command>tip</command>'s - “raise character,” specially designed for people with - broken caps-lock keys. Use <command>~s</command> as above and set the - variable <literal>raisechar</literal> to something reasonable. In - fact, you can set it to the same as the force character, if you never - expect to use either of these features.</para> - - <para>Here is a sample .tiprc file perfect for Emacs users who need to - type CTRL+2 and CTRL+A a lot:</para> - - <programlisting> -force=^^ -raisechar=^^</programlisting> - - <para>The ^^ is SHIFT+CTRL+6.</para> - </sect2> - - <sect2> - <title>How can I do file transfers with <command>tip</command>?</title> - - <para>If you are talking to another UNIX system, you can send and - receive files with <command>~p</command> (put) and - <command>~t</command> (take). These commands run - <command>cat</command> and <command>echo</command> on the remote - system to accept and send files. The syntax is:</para> - - <cmdsynopsis> - <command>~p</command> - <arg choice="plain">local-file</arg> - <arg choice="opt">remote-file</arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>~t</command> - <arg choice="plain">remote-file</arg> - <arg choice="opt">local-file</arg> - </cmdsynopsis> - - <para>There is no error checking, so you probably should use another - protocol, like zmodem.</para> - </sect2> - - <sect2> - <title>How can I run zmodem with <command>tip</command>?</title> - - <para>To receive files, start the sending program on the remote end. - Then, type <command>~C rz</command> to begin receiving them - locally.</para> - - <para>To send files, start the receiving program on the remote end. - Then, type <command>~C sz <replaceable>files</replaceable></command> - to send them to the remote system.</para> - </sect2> - </sect1> - - <sect1> - <title>Setting Up the Serial Console</title> - - <para><emphasis>&a.yokota; and &a.wpaul:</emphasis></para> - - <para><emphasis>The text is heavily based on - <filename>/sys/i386/boot/biosboot/README.serial</filename> written by - &a.wpaul;.</emphasis></para> - - <sect2 id="serialconsole-intro"> - <title>Introduction</title> - - <para>The FreeBSD/i386 operating system can boot on a system with only - a dumb terminal on a serial port as a console. Such a configuration - should be useful for two classes of people; system administrators who - wish to install FreeBSD on a dedicated file/compute/terminal server - machines that have no keyboard or monitor attached, and developers who - want to debug the kernel or device drivers.</para> - - <para>Starting from version 3.1, FreeBSD/i386 employs a three stage - bootstrap. The first two stages are in the boot block code which is - stored at the beginning of the FreeBSD slice on the boot disk. The - boot block will then load and run the boot loader - (<filename>/boot/loader</filename>) as the third stage code. (See - &man.boot.8; and &man.loader.8; for more details on the boot - process.)</para> - - <para>In order to set up the serial console you must configure the boot - block code, the boot loader code and the kernel.</para> - - <para>In FreeBSD version 3.0, the boot loader does not exist and there - are only two stages in the bootstrap; the boot blocks directly load - the kernel into memory. If you are using FreeBSD 3.0, then you should - disregard any reference to the boot loader in this section. You can - still use the serial port as a console.</para> - - <para>FreeBSD versions 2.X are quite different from 3.X, in that the - serial port driver, &man.sio.4;, must be configured in a different - way. This chapter will not describe the settings for version 2.X - systems. If you are using these older versions of FreeBSD, please - consult <filename>/sys/i386/boot/biosboot/README.serial</filename> - instead.</para> - </sect2> - - <sect2 id="serialconsole-howto"> - <title>6 Steps to Set up the Serial Console</title> - - <procedure> - <step> - <para>Prepare a serial cable.</para> - - <para>You will need either a null-modem cable or a standard serial - cable and a null-modem adapter. See <xref linkend="term"> for - a discussion on serial cables.</para> - </step> - - <step> - <para>Unplug your keyboard.</para> - - <para>Most PC systems probe for the keyboard during the Power-On - Self-Test (POST) and will generate an error if the keyboard is not - detected. Some machines complain loudly about the lack of a - keyboard and will not continue to boot until it is plugged - in.</para> - - <para>If your computer complains about the error, but boots anyway, - then you do not have to do anything special. (One machine with a - Phoenix BIOS that I have here merely says <errorname>Keyboard - failed</errorname> then continues to boot normally.)</para> - - <para>If your computer refuses to boot without a keyboard attached - then you will have to configure the BIOS so that it ignores this - error (if it can). Consult your motherboard's manual for details - on how to do this.</para> - - <tip> - <para>Setting the keyboard to “Not installed” in the - BIOS setup does <emphasis>not</emphasis> mean that you will not - be able to use your keyboard. All this does is tell the BIOS - not to probe for a keyboard at power-on so that it will not - complain if the keyboard is not plugged in. You can leave the - keyboard plugged in even with this flag set to “Not - installed” and the keyboard will still work.</para> - </tip> - - <note> - <para>If your system has a PS/2 mouse, chances are very good that - you may have to unplug your mouse as well as your keyboard. - This is because PS/2 mice share some hardware with the keyboard, - and leaving the mouse plugged in can fool the keyboard probe - into thinking the keyboard is still there. It is said that a - Gateway 2000 Pentium 90Mhz system with an AMI BIOS that behaves - this way. In general this is not a problem since the mouse is - not much good without the keyboard anyway.</para> - </note> - </step> - - <step> - <para>Plug a dumb terminal into <devicename>COM1:</devicename> - (<devicename>sio0</devicename>).</para> - - <para>If you do not have a dumb terminal, you can use an old PC/XT - with a modem program, or the serial port on another UNIX box. If - you do not have a <devicename>COM1:</devicename> - (<devicename>sio0</devicename>), get one. At this time, there is - no way to select a port other than <devicename>COM1:</devicename> - for the boot blocks without recompiling the boot blocks. If you - are already using <devicename>COM1:</devicename> for another - device, you will have to temporarily remove that device and - install a new boot block and kernel once you get FreeBSD up and - running. (It is assumed that <devicename>COM1:</devicename> will - be available on a file/compute/terminal server anyway; if you - really need <devicename>COM1:</devicename> for something else - (and you can not switch that something else to - <devicename>COM2:</devicename> (<devicename>sio1</devicename>)), - then you probably should not even be bothering with all this in - the first place.)</para> - </step> - - <step> - <para>Make sure the configuration file of your kernel has - appropriate flags set for <devicename>COM1:</devicename> - (<devicename>sio0</devicename>).</para> - - <para>Relevant flags are:</para> - - <variablelist> - <varlistentry> - <term><literal>0x10</literal></term> - - <listitem> - <para>Enables console support for this unit. The other - console flags are ignored unless this is set. Currently, at - most one unit can have console support; the first one (in - config file order) with this flag set is preferred. This - option alone will not make the serial port the console. Set - the following flag or use the <option>-h</option> option - described below, together with this flag.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>0x20</literal></term> - - <listitem> - <para>Forces this unit to be the console (unless there is - another higher priority console), regardless of the - <option>-h</option> option discussed below. This flag - replaces the <literal>COMCONSOLE</literal> option in FreeBSD - versions 2.X. The flag <literal>0x20</literal> must be used - together with the <option>0x10</option> flag.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>0x40</literal></term> - - <listitem> - <para>Reserves this unit (in conjunction with - <literal>0x10</literal>) and makes the unit unavailable for - normal access. You should not set this flag to the serial - port unit which you want to use as the serial console. The - only use of this flag is to designate the unit for kernel - remote debugging. See <xref linkend="kerneldebug"> for more - information on remote debugging.</para> - - <note> - <para>In FreeBSD 4.0-CURRENT or later the semantics of the - flag <literal>0x40</literal> are slightly different and - there is another flag to specify a serial port for remote - debugging.</para> - </note> - </listitem> - </varlistentry> - </variablelist> - - <para>Example:</para> - - <programlisting> -device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting> - - <para>See &man.sio.4; for more details.</para> - - <para>If the flags were not set, you need to run UserConfig (on a - different console) or recompile the kernel.</para> - </step> - - <step> - <para>Create <filename>boot.config</filename> in the root directory - of the <literal>a</literal> partition on the boot drive.</para> - - <para>This file will instruct the boot block code how you would like - to boot the system. In order to activate the serial console, you - need one or more of the following options—if you want - multiple options, include them all on the same line:</para> - - <variablelist> - <varlistentry> - <term><option>-h</option></term> - - <listitem> - <para>Toggles internal and serial consoles. You can use this - to switch console devices. For instance, if you boot from - the internal (video) console, you can use - <option>-h</option> to direct the boot loader and the kernel - to use the serial port as its console device. Alternatively, - if you boot from the serial port, you can use the - <option>-h</option> to tell the boot loader and the kernel - to use the video display as the console instead.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-D</option></term> - - <listitem> - <para>Toggles single and dual console configurations. In the - single configuration the console will be either the internal - console (video display) or the serial port, depending on the - state of the <option>-h</option> option above. In the dual - console configuration, both the video display and the - serial port will become the console at the same time, - regardless of the state of the <option>-h</option> option. - However, that the dual console configuration takes effect - only during the boot block is running. Once the boot loader - gets control, the console specified by the - <option>-h</option> option becomes the only console.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-P</option></term> - - <listitem> - <para>Makes the boot block probe the keyboard. If no keyboard - is found, the <option>-D</option> and <option>-h</option> - options are automatically set.</para> - - <note> - <para>Due to space constraints in the current version of the - boot blocks, the <option>-P</option> option is capable of - detecting extended keyboards only. Keyboards with less - than 101 keys (and without F11 and F12 keys) may not be - detected. Keyboards on some laptop computers may not be - properly found because of this limitation. If this is to - be the case with your system, you have to abandon using - the <option>-P</option> option. Unfortunately there is no - workaround for this problem.</para> - </note> - </listitem> - </varlistentry> - </variablelist> - - <para>Use either the <option>-P</option> option to select the - console automatically, or the <option>-h</option> option to - activate the serial console.</para> - - <para>You may include other options described in &man.boot.8; as - well.</para> - - <para>The options, except for <option>-P</option>, will be passed to - the boot loader (<filename>/boot/loader</filename>). The boot - loader will determine which of the internal video or the serial - port should become the console by examining the state of the - <option>-h</option> option alone. This means that if you specify - the <option>-D</option> option but not the <option>-h</option> - option in <filename>/boot.config</filename>, you can use the - serial port as the console only during the boot block; the boot - loader will use the internal video display as the console.</para> - </step> - - <step> - <para>Boot the machine.</para> - - <para>When you start your FreeBSD box, the boot blocks will echo the - contents of <filename>/boot.config</filename> to the console. For - example;</para> - - <screen>/boot.config: -P -Keyboard: no</screen> - - <para>The second line appears only if you put <option>-P</option> in - <filename>/boot.config</filename> and indicates presence/absence - of the keyboard. These messages go to either serial or internal - console, or both, depending on the option in - <filename>/boot.config</filename>.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Options</entry> - <entry>Message goes to</entry> - </row> - </thead> - - <tbody> - <row> - <entry>none</entry> - <entry>internal console</entry> - </row> - - <row> - <entry><option>-h</option></entry> - <entry>serial console</entry> - </row> - - <row> - <entry><option>-D</option></entry> - <entry>serial and internal consoles</entry> - </row> - - <row> - <entry><option>-Dh</option></entry> - <entry>serial and internal consoles</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard present</entry> - <entry>internal console</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard absent</entry> - <entry>serial console</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>After the above messages, there will be a small pause before - the boot blocks continue loading the boot loader and before any - further messages printed to the console. Under normal - circumstances, you do not need to interrupt the boot blocks, but - you may want to do so in order to make sure things are set up - correctly.</para> - - <para>Hit any key, other than Enter/Return, at the console to - interrupt the boot process. The boot blocks will then prompt you - for further action. You should now see something like:</para> - - <screen>>> FreeBSD/i386 BOOT -Default: 0:wd(0,a)/boot/loader -boot:</screen> - - <para>Verify the above message appears on either the serial or - internal console or both, according to the options you put in - <filename>/boot.config</filename>. If the message appears in the - correct console, hit Enter/Return to continue the boot - process.</para> - - <para>If you want the serial console but you do not see the prompt - on the serial terminal, something is wrong with your settings. In - the meantime, you enter <option>-h</option> and hit Enter/Return - (if possible) to tell the boot block (and then the boot loader and - the kernel) to choose the serial port for the console. Once the - system is up, go back and check what went wrong.</para> - </step> - </procedure> - - <para>After the boot loader is loaded and you are in the third stage of - the boot process you can still switch between the internal console and - the serial console by setting appropriate environment variables in the - boot loader. See <xref linkend="serialconsole-loader">.</para> - </sect2> - - <sect2 id="serialconsole-summary"> - <title>Summary</title> - - <para>Here is the summary of various settings discussed in this section - and the console eventually selected.</para> - - <sect3> - <title>Case 1: You set the flags to 0x10 for sio0</title> - - <programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting> - - <informaltable frame="none"> - <tgroup cols="4"> - <thead> - <row> - <entry>Options in /boot.config</entry> - <entry>Console during boot blocks</entry> - <entry>Console during boot loader</entry> - <entry>Console in kernel</entry> - </row> - </thead> - - <tbody> - <row> - <entry>nothing</entry> - <entry>internal</entry> - <entry>internal</entry> - <entry>internal</entry> - </row> - - <row> - <entry><option>-h</option></entry> - <entry>serial</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-D</option></entry> - <entry>serial and internal</entry> - <entry>internal</entry> - <entry>internal</entry> - </row> - - <row> - <entry><option>-Dh</option></entry> - <entry>serial and internal</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard present</entry> - <entry>internal</entry> - <entry>internal</entry> - <entry>internal</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard absent</entry> - <entry>serial and internal</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - - <sect3> - <title>Case 2: You set the flags to 0x30 for sio0</title> - - <programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4</programlisting> - - <informaltable frame="none"> - <tgroup cols="4"> - <thead> - <row> - <entry>Options in /boot.config</entry> - <entry>Console during boot blocks</entry> - <entry>Console during boot loader</entry> - <entry>Console in kernel</entry> - </row> - </thead> - - <tbody> - <row> - <entry>nothing</entry> - <entry>internal</entry> - <entry>internal</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-h</option></entry> - <entry>serial</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-D</option></entry> - <entry>serial and internal</entry> - <entry>internal</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-Dh</option></entry> - <entry>serial and internal</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard present</entry> - <entry>internal</entry> - <entry>internal</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard absent</entry> - <entry>serial and internal</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - </sect2> - - <sect2 id="serialconsole-tips"> - <title>Tips for the Serial Console</title> - - <sect3> - <title>Setting A Faster Serial Port Speed</title> - - <para>By default the serial port settings are set to 9600 baud, 8 - bits, no parity, 1 stop bit. If you wish to change the speed, you - need to recompile at least the boot blocks. Add the following line - to <filename>/etc/make.conf</filename> and compile new boot - blocks:</para> - - <programlisting>BOOT_COMCONSOLE_SPEED=19200</programlisting> - - <para>If the serial console is configured in some other way than by - booting with <option>-h</option>, or if the serial console used by - the kernel is different from the one used by the boot blocks, then - you must also add the following option to the kernel configuration - file and compile a new kernel:</para> - - <programlisting>options CONSPEED=19200</programlisting> - </sect3> - - <sect3 id="serialconsole-com2"> - <title>Using Serial Port Other Than <devicename>sio0</devicename> For - The Console</title> - - <para>Using a port other than <devicename>sio0</devicename> as the - console requires some recompiling. If you want to use another - serial port for whatever reasons, recompile the boot blocks, the - boot loader and the kernel as follows.</para> - - <procedure> - <step> - <para>Get the kernel source.</para> - </step> - - <step> - <para>Edit <filename>/etc/make.conf</filename> and set - <literal>BOOT_COMCONSOLE_PORT</literal> to the address of the - port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only - <devicename>sio0</devicename> through - <devicename>sio3</devicename> (<devicename>COM1:</devicename> - through <devicename>COM4:</devicename>) can be used; multiport - serial cards will not work. No interrupt setting is - needed.</para> - </step> - - <step> - <para>Create a custom kernel configuration file and add - appropriate flags for the serial port you want to use. For - example, if you want to make <devicename>sio1</devicename> - (<devicename>COM2:</devicename>) the console:</para> - - <programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3</programlisting> - - <para>or</para> - - <programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3</programlisting> - - <para>The console flags for the other serial ports should not be - set.</para> - </step> - - <step> - <para>Recompile and install the boot blocks:</para> - - <screen>&prompt.root; <userinput>cd /sys/boot/i386/boot2</userinput> -&prompt.root; <userinput>make</userinput> -&prompt.root; <userinput>make install</userinput></screen> - </step> - - <step> - <para>Recompile and install the boot loader:</para> - - <screen>&prompt.root; <userinput>cd /sys/boot/i386/loader</userinput> -&prompt.root; <userinput>make</userinput> -&prompt.root; <userinput>make install</userinput></screen> - </step> - - <step> - <para>Rebuild and install the kernel.</para> - </step> - - <step> - <para>Write the boot blocks to the boot disk with - &man.disklabel.8; and boot from the new kernel.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Entering the DDB Debugger from the Serial Line</title> - - <para>If you wish to drop into the kernel debugger from the serial - console (useful for remote diagnostics, but also dangerous if you - generate a spurious BREAK on the serial port!) then you should - compile your kernel with the following options:</para> - - <programlisting>options BREAK_TO_DEBUGGER -options DDB</programlisting> - </sect3> - - <sect3> - <title>Getting a Login Prompt on the Serial Console</title> - - <para>While this is not required, you may wish to get a - <emphasis>login</emphasis> prompt over the serial line, now that you - can see boot messages and can enter the kernel debugging session - through the serial console. Here is how to do it.</para> - - <para>Open the file <filename>/etc/ttys</filename> with an editor - and locate the lines:</para> - - <programlisting>ttyd0 "/usr/libexec/getty std.9600" unknown off secure -ttyd1 "/usr/libexec/getty std.9600" unknown off secure -ttyd2 "/usr/libexec/getty std.9600" unknown off secure -ttyd3 "/usr/libexec/getty std.9600" unknown off secure</programlisting> - - <para><literal>ttyd0</literal> through <literal>ttyd3</literal> - corresponds to <devicename>COM1</devicename> through - <devicename>COM4</devicename>. Change <literal>off</literal> to - <literal>on</literal> for the desired port. If you have changed the - speed of the serial port, you need to change - <literal>std.9600</literal> to match the current setting, e.g. - <literal>std.19200</literal>.</para> - - <para>You may also want to change the terminal type from - <literal>unknown</literal> to the actual type of your serial - terminal.</para> - - <para>After editing the file, you must <command>kill -HUP 1</command> - to make this change take effect.</para> - </sect3> - </sect2> - - <sect2 id="serialconsole-loader"> - <title>Changing Console from the Boot Loader</title> - - <para>Previous sections described how to set up the serial console by - tweaking the boot block. This section shows that you can specify the - console by entering some commands and environment variables in the - boot loader. As the boot loader is invoked as the third stage of the - boot process, after the boot block, the settings in the boot loader - will override the settings in the boot block.</para> - - <sect3> - <title>Setting Up the Serial Console</title> - - <para>You can easily specify the boot loader and the kernel to use the - serial console by writing just one line in - <filename>/boot/loader.rc</filename>:</para> - - <programlisting>set console=comconsole</programlisting> - - <para>This will take effect regardless of the settings in the boot - block discussed in the previous section.</para> - - <para>You had better put the above line as the first line of - <filename>/boot/loader.rc</filename> so as to see boot messages on - the serial console as early as possible.</para> - - <para>Likewise, you can specify the internal console as:</para> - - <programlisting>set console=vidconsole</programlisting> - - <para>If you do not set the boot loader environment variable - <envar>console</envar>, the boot loader, and subsequently the - kernel, will use whichever console indicated by the - <option>-h</option> option in the boot block.</para> - - <para>In versions 3.2 or later, you may specify the console in - <filename>/boot/loader.conf.local</filename> or - <filename>/boot/loader.conf</filename>, rather than in - <filename>/boot/loader.rc</filename>. In this method your - <filename>/boot/loader.rc</filename> should look like:</para> - - <programlisting>include /boot/loader.4th -start</programlisting> - - <para>Then, create <filename>/boot/loader.conf.local</filename> and - put the following line there.</para> - - <programlisting>console=comconsole</programlisting> - - <para>or</para> - - <programlisting>console=vidconsole</programlisting> - - <para>See &man.loader.conf.5; for more information.</para> - - <note> - <para>At the moment, the boot loader has no option equivalent to the - <option>-P</option> option in the boot block, and there is no - provision to automatically select the internal console and the - serial console based on the presence of the keyboard.</para> - </note> - </sect3> - - <sect3> - <title>Using Serial Port Other than <devicename>sio0</devicename> for - the Console</title> - - <para>You need to recompile the boot loader to use a serial port other - than <devicename>sio0</devicename> for the serial console. Follow the - procedure described in <xref linkend="serialconsole-com2">.</para> - </sect3> - </sect2> - - <sect2 id="serialconsole-caveats"> - <title>Caveats</title> - - <para>The idea here is to allow people to set up dedicated servers that - require no graphics hardware or attached keyboards. Unfortunately, - while (most?) every system will let you boot without a keyboard, there - are quite a few that will not let you boot without a graphics adapter. - Machines with AMI BIOSes can be configured to boot with no graphics - adapter installed simply by changing the `graphics adapter' setting in - the CMOS configuration to `Not installed.'</para> - - <para>However, many machines do not support this option and will refuse - to boot if you have no display hardware in the system. With these - machines, you'll have to leave some kind of graphics card plugged in, - (even if it's just a junky mono board) although you will not have to - attach a monitor into it. You might also try installing an AMI - BIOS.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/staff/chapter.sgml b/en/handbook/staff/chapter.sgml deleted file mode 100644 index f9e8e1acee..0000000000 --- a/en/handbook/staff/chapter.sgml +++ /dev/null @@ -1,933 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.55 1999-08-11 13:53:13 alfred Exp $ ---> - -<!-- - Please try to keep the CVSROOT/avail file in sync with the list of - FreeBSD developers. ---> - -<chapter id="staff"> - <title>FreeBSD Project Staff</title> - - <para>The FreeBSD Project is managed and operated by the following groups of - people:</para> - - <sect1 id="staff-core"> - <title>The FreeBSD Core Team</title> - - <para>The FreeBSD core team constitutes the project's “Board of - Directors”, responsible for deciding the project's overall goals - and direction as well as managing <link linkend="staff-who">specific - areas</link> of the FreeBSD project landscape.</para> - - <para>(in alphabetical order by last name):</para> - - <itemizedlist> - <listitem> - <para>&a.asami;</para> - </listitem> - - <listitem> - <para>&a.jmb;</para> - </listitem> - - <listitem> - <para>&a.ache;</para> - </listitem> - - <listitem> - <para>&a.bde;</para> - </listitem> - - <listitem> - <para>&a.gibbs;</para> - </listitem> - - <listitem> - <para>&a.dg;</para> - </listitem> - - <listitem> - <para>&a.jkh;</para> - </listitem> - - <listitem> - <para>&a.phk;</para> - </listitem> - - <listitem> - <para>&a.rich;</para> - </listitem> - - <listitem> - <para>&a.gpalmer;</para> - </listitem> - - <listitem> - <para>&a.jdp;</para> - </listitem> - - <listitem> - <para>&a.dfr;</para> - </listitem> - - <listitem> - <para>&a.sos;</para> - </listitem> - - <listitem> - <para>&a.peter;</para> - </listitem> - - <listitem> - <para>&a.wollman;</para> - </listitem> - - <listitem> - <para>&a.joerg;</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="staff-committers"> - <title>The FreeBSD Developers</title> - - <para>These are the people who have commit privileges and do the - engineering work on the FreeBSD source tree. All core team members are - also developers.</para> - - <itemizedlist> - <listitem> - <para>&a.ugen;</para> - </listitem> - - <listitem> - <para>&a.dbaker;</para> - </listitem> - - <listitem> - <para>&a.mbarkah;</para> - </listitem> - - <listitem> - <para>&a.stb;</para> - </listitem> - - <listitem> - <para>&a.pb;</para> - </listitem> - - <listitem> - <para>&a.abial;</para> - </listitem> - - <listitem> - <para>&a.jb;</para> - </listitem> - - <listitem> - <para>&a.torstenb;</para> - </listitem> - - <listitem> - <para>&a.dburr;</para> - </listitem> - - <listitem> - <para>&a.charnier;</para> - </listitem> - - <listitem> - <para>&a.luoqi;</para> - </listitem> - - <listitem> - <para>&a.ejc;</para> - </listitem> - - <listitem> - <para>&a.kjc;</para> - </listitem> - - <listitem> - <para>&a.gclarkii;</para> - </listitem> - - <listitem> - <para>&a.archie;</para> - </listitem> - - <listitem> - <para>&a.chris;</para> - </listitem> - - <listitem> - <para>&a.alc;</para> - </listitem> - - <listitem> - <para>&a.cracauer;</para> - </listitem> - - <listitem> - <para>&a.adam;</para> - </listitem> - - <listitem> - <para>&a.dillon;</para> - </listitem> - - <listitem> - <para>&a.mdodd;</para> - </listitem> - - <listitem> - <para>&a.dufault;</para> - </listitem> - - <listitem> - <para>&a.uhclem;</para> - </listitem> - - <listitem> - <para>&a.tegge;</para> - </listitem> - - <listitem> - <para>&a.deischen;</para> - </listitem> - - <listitem> - <para>&a.eivind;</para> - </listitem> - - <listitem> - <para>&a.julian;</para> - </listitem> - - <listitem> - <para>&a.rse;</para> - </listitem> - - <listitem> - <para>&a.ru;</para> - </listitem> - - <listitem> - <para>&a.se;</para> - </listitem> - - <listitem> - <para>&a.jasone;</para> - </listitem> - - <listitem> - <para>&a.sef;</para> - </listitem> - - <listitem> - <para>&a.green;</para> - </listitem> - - <listitem> - <para>&a.fenner;</para> - </listitem> - - <listitem> - <para>&a.jfieber;</para> - </listitem> - - <listitem> - <para>&a.jfitz;</para> - </listitem> - - <listitem> - <para>&a.scrappy;</para> - </listitem> - - <listitem> - <para>&a.lars;</para> - </listitem> - - <listitem> - <para>&a.dirk;</para> - </listitem> - - <listitem> - <para>&a.shige;</para> - </listitem> - - <listitem> - <para>&a.billf;</para> - </listitem> - - <listitem> - <para>&a.gallatin;</para> - </listitem> - - <listitem> - <para>&a.tg;</para> - </listitem> - - <listitem> - <para>&a.brandon;</para> - </listitem> - - <listitem> - <para>&a.graichen;</para> - </listitem> - - <listitem> - <para>&a.cg;</para> - </listitem> - - <listitem> - <para>&a.jgreco;</para> - </listitem> - - <listitem> - <para>&a.rgrimes;</para> - </listitem> - - <listitem> - <para>&a.jmg;</para> - </listitem> - - <listitem> - <para>&a.hanai;</para> - </listitem> - - <listitem> - <para>&a.mharo;</para> - </listitem> - - <listitem> - <para>&a.thepish;</para> - </listitem> - - <listitem> - <para>&a.jhay;</para> - </listitem> - - <listitem> - <para>&a.sheldonh;</para> - </listitem> - - <listitem> - <para>&a.helbig;</para> - </listitem> - - <listitem> - <para>&a.ghelmer;</para> - </listitem> - - <listitem> - <para>&a.erich;</para> - </listitem> - - <listitem> - <para>&a.nhibma;</para> - </listitem> - - <listitem> - <para>&a.flathill;</para> - </listitem> - - <listitem> - <para>&a.hosokawa;</para> - </listitem> - - <listitem> - <para>&a.hsu;</para> - </listitem> - - <listitem> - <para>&a.foxfair;</para> - </listitem> - - <listitem> - <para>&a.tom;</para> - </listitem> - - <listitem> - <para>&a.mph;</para> - </listitem> - - <listitem> - <para>&a.shin;</para> - </listitem> - - <listitem> - <para>&a.itojun;</para> - </listitem> - - <listitem> - <para>&a.iwasaki;</para> - </listitem> - - <listitem> - <para>&a.mjacob;</para> - </listitem> - - <listitem> - <para>&a.gj;</para> - </listitem> - - <listitem> - <para>&a.nsj;</para> - </listitem> - - <listitem> - <para>&a.ljo;</para> - </listitem> - - <listitem> - <para>&a.kato;</para> - </listitem> - - <listitem> - <para>&a.andreas;</para> - </listitem> - - <listitem> - <para>&a.motoyuki;</para> - </listitem> - - <listitem> - <para>&a.jkoshy;</para> - </listitem> - - <listitem> - <para>&a.kuriyama;</para> - </listitem> - - <listitem> - <para>&a.grog;</para> - </listitem> - - <listitem> - <para>&a.jlemon;</para> - </listitem> - - <listitem> - <para>&a.truckman;</para> - </listitem> - - <listitem> - <para>&a.lile;</para> - </listitem> - - <listitem> - <para>&a.kevlo;</para> - </listitem> - - <listitem> - <para>&a.imp;</para> - </listitem> - - <listitem> - <para>&a.jmacd;</para> - </listitem> - - <listitem> - <para>&a.smace;</para> - </listitem> - - <listitem> - <para>&a.gehenna;</para> - </listitem> - - <listitem> - <para>&a.mckay;</para> - </listitem> - - <listitem> - <para>&a.mckusick;</para> - </listitem> - - <listitem> - <para>&a.ken;</para> - </listitem> - - <listitem> - <para>&a.hm;</para> - </listitem> - - <listitem> - <para>&a.tedm;</para> - </listitem> - - <listitem> - <para>&a.jim;</para> - </listitem> - - <listitem> - <para>&a.marcel;</para> - </listitem> - - <listitem> - <para>&a.amurai;</para> - </listitem> - - <listitem> - <para>&a.markm;</para> - </listitem> - - <listitem> - <para>&a.max;</para> - </listitem> - - <listitem> - <para>&a.newton;</para> - </listitem> - - <listitem> - <para>&a.rnordier;</para> - </listitem> - - <listitem> - <para>&a.davidn;</para> - </listitem> - - <listitem> - <para>&a.obrien;</para> - </listitem> - - <listitem> - <para>&a.danny;</para> - </listitem> - - <listitem> - <para>&a.ljo;</para> - </listitem> - - <listitem> - <para>&a.fsmp;</para> - </listitem> - - <listitem> - <para>&a.smpatel;</para> - </listitem> - - <listitem> - <para>&a.wpaul;</para> - </listitem> - - <listitem> - <para>&a.alfred;</para> - </listitem> - - <listitem> - <para>&a.wes;</para> - </listitem> - - <listitem> - <para>&a.cpiazza;</para> - </listitem> - - <listitem> - <para>&a.steve;</para> - </listitem> - - <listitem> - <para>&a.mpp;</para> - </listitem> - - <listitem> - <para>&a.jraynard;</para> - </listitem> - - <listitem> - <para>&a.darrenr;</para> - </listitem> - - <listitem> - <para>&a.csgr;</para> - </listitem> - - <listitem> - <para>&a.martin;</para> - </listitem> - - <listitem> - <para>&a.paul;</para> - </listitem> - - <listitem> - <para>&a.roberto;</para> - </listitem> - - <listitem> - <para>&a.chuckr;</para> - </listitem> - - <listitem> - <para>&a.guido;</para> - </listitem> - - <listitem> - <para>&a.dima;</para> - </listitem> - - <listitem> - <para>&a.sada;</para> - </listitem> - - <listitem> - <para>&a.nsayer;</para> - </listitem> - - <listitem> - <para>&a.wosch;</para> - </listitem> - - <listitem> - <para>&a.ats;</para> - </listitem> - - <listitem> - <para>&a.dick;</para> - </listitem> - - <listitem> - <para>&a.jseger;</para> - </listitem> - - <listitem> - <para>&a.simokawa;</para> - </listitem> - - <listitem> - <para>&a.vanilla;</para> - </listitem> - - <listitem> - <para>&a.msmith;</para> - </listitem> - - <listitem> - <para>&a.des;</para> - </listitem> - - <listitem> - <para>&a.brian;</para> - </listitem> - - <listitem> - <para>&a.mks;</para> - </listitem> - - <listitem> - <para>&a.stark;</para> - </listitem> - - <listitem> - <para>&a.karl;</para> - </listitem> - - <listitem> - <para>&a.sumikawa;</para> - </listitem> - - <listitem> - <para>&a.nyan;</para> - </listitem> - - <listitem> - <para>&a.tanimura;</para> - </listitem> - - <listitem> - <para>&a.taoka;</para> - </listitem> - - <listitem> - <para>&a.dt;</para> - </listitem> - - <listitem> - <para>&a.cwt;</para> - </listitem> - - <listitem> - <para>&a.pst;</para> - </listitem> - - <listitem> - <para>&a.hoek;</para> - </listitem> - - <listitem> - <para>&a.nectar;</para> - </listitem> - - <listitem> - <para>&a.swallace;</para> - </listitem> - - <listitem> - <para>&a.dwhite;</para> - </listitem> - - <listitem> - <para>&a.nate;</para> - </listitem> - - <listitem> - <para>&a.yokota;</para> - </listitem> - - <listitem> - <para>&a.jmz;</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="staff-doc"> - <title>The FreeBSD Documentation Project</title> - - <para>The <ulink URL="http://www.FreeBSD.org/docproj.html">FreeBSD - Documentation Project</ulink> is responsible for a number of different - services, each service being run by an individual and his - <emphasis>deputies</emphasis> (if any):</para> - - <variablelist> - <varlistentry> - <term>Documentation Project Manager</term> - - <listitem> - <para>&a.nik;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Webmaster</term> - - <listitem> - <para>&a.wosch;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook & FAQ Editor</term> - - <listitem> - <para>&a.faq;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>News Editor</term> - - <listitem> - <para>&a.nsj;</para> - - <para><emphasis>Deputy:</emphasis> &a.john;</para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>In the Press Editor</term> - - <listitem> - <para>&a.jkoshy</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FreeBSD Really-Quick NewsLetter Editor</term> - - <listitem> - <para>Chris Coleman <email>chrisc@vmunix.com</email></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Gallery Editor</term> - - <listitem> - <para>&a.nsj;</para> - - <para><emphasis>Deputy:</emphasis> &a.cawimm;</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>Commercial Editor</term> - - <listitem> - <para>&a.nik;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Web Changes Editor</term> - - <listitem> - <para>-</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>User Groups Editor</term> - - <listitem> - <para>-</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LinuxDoc to DocBook conversion</term> - - <listitem> - <para>&a.nik;</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="staff-who"> - <title>Who Is Responsible for What</title> - - <variablelist> - <varlistentry> - <term>Principal Architect</term> - - <listitem> - <para>&a.dg;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink - url="http://www.FreeBSD.org/docproj/docproj.html">Documentation - Project Manager</ulink></term> - - <listitem> - <para>&a.nik;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><link linkend="l10n">Internationalization</link></term> - - <listitem> - <para>&a.ache;</para> - </listitem> - </varlistentry> - - <varlistentry><term>Networking</term> - - <listitem> - <para>&a.wollman;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><link linkend="eresources-mail">Postmaster</link></term> - - <listitem> - <para>&a.jmb;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Release Coordinator</term> - - <listitem> - <para>&a.jkh;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Public Relations & Corporate Liaison</term> - - <listitem> - <para>&a.jkh;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.FreeBSD.org/security/">Security - Officer</ulink></term> - - <listitem> - <para>&a.imp;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.FreeBSD.org/support.html#cvs">Source - Repository Managers</ulink></term> - - <listitem> - <para>Principal: &a.peter;</para> - - <para>Assistant: &a.jdp;</para> - - <para>International (Crypto): &a.markm;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.FreeBSD.org/ports/">Ports - Manager</ulink></term> - - <listitem> - <para>&a.asami;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>XFree86 Project, Inc. Liaison</term> - - <listitem> - <para>&a.rich;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><link linkend="eresources-news">Usenet Support</link></term> - - <listitem> - <para>&a.joerg;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.FreeBSD.org/support.html#gnats">GNATS - Administrator</ulink></term> - - <listitem> - <para>&a.steve;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink - url="http://www.FreeBSD.org/internal/">Webmaster</ulink></term> - - <listitem> - <para>&a.wosch;</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - diff --git a/en/handbook/x11/chapter.sgml b/en/handbook/x11/chapter.sgml deleted file mode 100644 index 19bfa17e1c..0000000000 --- a/en/handbook/x11/chapter.sgml +++ /dev/null @@ -1,25 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.5 1999-03-08 22:04:49 nik Exp $ ---> - -<chapter id="x11"> - <title>The X Window System</title> - - <para>Pending the completion of this section, please refer to documentation - supplied by the <ulink URL="http://www.xfree86.org/">The XFree86 Project, - Inc</ulink>.</para> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - |