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 | |
| parent | c49d00f6013ff123e1a0039c301be00b31edeec2 (diff) | |
Notes
Diffstat (limited to 'en')
78 files changed, 0 insertions, 61496 deletions
diff --git a/en/Makefile b/en/Makefile deleted file mode 100644 index 04e5d0f529..0000000000 --- a/en/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -# $Id: Makefile,v 1.1 1999-03-08 21:43:32 nik Exp $ - -SUBDIR = handbook - -.include <bsd.subdir.mk> 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: ---> - diff --git a/en/share/sgml/bookinfo.ent b/en/share/sgml/bookinfo.ent deleted file mode 100644 index bd79240b51..0000000000 --- a/en/share/sgml/bookinfo.ent +++ /dev/null @@ -1,12 +0,0 @@ -<!-- - References to other files that can be included within a DocBook - BookInfo element. - - Entity names take the form "bookinfo.<element>", where <element> is - the name of the outermost element in the entity. Examples would - be "bookinfo.legalnotice", and "bookinfo.preface". - - $Id: bookinfo.ent,v 1.1 1999-05-05 20:13:19 nik Exp $ ---> - -<!ENTITY bookinfo.legalnotice SYSTEM "legalnotice.sgml"> diff --git a/en/share/sgml/legalnotice.sgml b/en/share/sgml/legalnotice.sgml deleted file mode 100644 index 220a937b88..0000000000 --- a/en/share/sgml/legalnotice.sgml +++ /dev/null @@ -1,44 +0,0 @@ -<!-- - Standard FreeBSD Documentation Project Legal Notice. - - $Id: legalnotice.sgml,v 1.1 1999-05-05 20:12:11 nik Exp $ ---> - -<legalnotice> - <para>Redistribution and use in source (SGML DocBook) and 'compiled' - forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions are - met:</para> - - <orderedlist> - <listitem> - <para>Redistributions of source code (SGML DocBook) must retain the - above copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified.</para> - </listitem> - - <listitem> - <para>Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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.</para> - </listitem> - </orderedlist> - - <important> - <para>THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION - PROJECT "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 - THE FREEBSD DOCUMENTATION PROJECT 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 DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH - DAMAGE.</para> - </important> -</legalnotice> - diff --git a/en/tutorials/Makefile b/en/tutorials/Makefile deleted file mode 100644 index 0201a9db51..0000000000 --- a/en/tutorials/Makefile +++ /dev/null @@ -1,26 +0,0 @@ -# $Id: Makefile,v 1.18 1999-04-27 18:33:23 nik Exp $ - -DOCS?= index.sgml -SUBDIR= devel -SUBDIR+= diskformat -SUBDIR+= disklessx -SUBDIR+= fonts -SUBDIR+= mh -SUBDIR+= multios -SUBDIR+= newuser -DOCSUBDIR= docproj-primer -DOCSUBDIR+= ddwg -DOCSUBDIR+= ppp -SGMLOPTS+= -links -hdr ${.CURDIR}/doc.hdr -ftr ${.CURDIR}/doc.ftr - - -.if defined $(NEW_BUILD) -SUBDIR= -.endif -.if defined(DOCBOOK_ONLY) && !empty(DOCBOOK_ONLY) -DOCSUBDIR= -.endif - -WEBBASE?= /data/ - -.include "../web.mk" diff --git a/en/tutorials/Makefile.inc b/en/tutorials/Makefile.inc deleted file mode 100644 index 7da7fe75c2..0000000000 --- a/en/tutorials/Makefile.inc +++ /dev/null @@ -1,4 +0,0 @@ -# $Id: Makefile.inc,v 1.4 1997-07-01 03:52:21 max Exp $ - -WEBBASE?= /data/tutorials -SGMLOPTS+= -hdr ${.CURDIR}/../doc.hdr -ftr ${.CURDIR}/../doc.ftr diff --git a/en/tutorials/ddwg/Makefile b/en/tutorials/ddwg/Makefile deleted file mode 100644 index f28e8dcab7..0000000000 --- a/en/tutorials/ddwg/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:11 max Exp $ - -DOC= ddwg -SRCS= ddwg.sgml - -.include <bsd.sgml.mk> diff --git a/en/tutorials/ddwg/ddwg.sgml b/en/tutorials/ddwg/ddwg.sgml deleted file mode 100644 index f9f14bcb19..0000000000 --- a/en/tutorials/ddwg/ddwg.sgml +++ /dev/null @@ -1,1243 +0,0 @@ -<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> - -<!-- - ++++++++++++++++++++++++++++++++++++++++++++++++++ - ++ file: /home/erich/lib/src/sgml/ddwg.sgml - ++ - ++ Copyright Eric L. Hernes - Wednesday, August 2, 1995 - ++ - ++ $Id: ddwg.sgml,v 1.7 1999-08-01 10:00:43 nik Exp $ - ++ - ++ Sgml doc for something - --> - -<article> - -<title>FreeBSD Device Driver Writer's Guide -<author>Eric L. Hernes, <tt/erich@rrnet.com/ -<date>Wednesday, May 29, 1996 - -<abstract> - -This document describes how to add a device driver to FreeBSD. It is -<it/not/ intended to be a tutorial on UNIX device drivers in general. -It is intended for device driver authors, familiar with the UNIX -device driver model, to work on FreeBSD. - -</abstract> - -<toc> - -<sect>2.x specific - -<p>Due to changes in FreeBSD over time, this guide is only accurate as -regards FreeBSD 2.x. A replacement guide for FreeBSD 3.x and beyond -is being written. Please contact Jeroen Ruigrok <tt/<asmodai@wxs.nl>/ -if you would like to help with this. - -<sect> Overview - -<p> <it> -The FreeBSD kernel is very well documented, unfortunately it's all -in `C'. -</it> - -<sect> Types of drivers. - -<sect1> Character - -<sect2> Data Structures -<p> <tt/struct cdevsw/ Structure - -<sect2> Entry Points -<sect3> d_open() -<p> -d_open() takes several arguments, the formal list looks something like: -<code> -int -d_open(dev_t dev, int flag, int mode, struct proc *p) -</code> -d_open() is called on <em/every/ open of the device. -<p> - -The <tt/dev/ argument contains the major and minor number of the -device opened. These are available through the macros <tt/major()/ and -<tt/minor()/ -<p> - -The <tt/flag/ and <tt/mode/ arguments are as described in the -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?open(2)" name="open(2)"> -manual page. It is recommended that you check these for access modes -in <sys/fcntl.h> and do what is required. For example if <tt/flag/ -is (O_NONBLOCK | O_EXLOCK) the open should fail if either it would -block, or exclusive access cannot be granted. -<p> - -The <tt/p/ argument contains all the information about the current -process. - -<sect3> d_close() -<p> -d_close() takes the same argument list as d_open(): -<code> -int -d_close(dev_t dev , int flag , int mode , struct proc *p) -</code> - -d_close() is only called on the last close of your device (per minor -device). For example in the following code fragment, d_open() is called -3 times, but d_close() is called only once. -<code> - ... - fd1=open("/dev/mydev", O_RDONLY); - fd2=open("/dev/mydev", O_RDONLY); - fd3=open("/dev/mydev", O_RDONLY); - ... - <useful stuff with fd1, fd2, fd3 here> - ... - close(fd1); - close(fd2); - close(fd3); - ... -</code> - -The arguments are similar to those described above for -d_open(). - -<sect3> d_read() and d_write() -<p> -d_read() and d_write take the following argument lists: -<code> -int -d_read(dev_t dev, struct uio *uio, int flat) -int -d_write(dev_t dev, struct uio *uio, int flat) -</code> - -The d_read() and d_write() entry points are called when -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?read(2)" name="read(2)"> and -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?write(2)" name="write(2)"> -are called on your device from user-space. The transfer -of data can be handled through the kernel support routine uiomove(). - -<sect3> d_ioctl() -<p> -It's argument list is as follows: -<code> -int -d_ioctl(dev_t dev, int cmd, caddr_t arg, int flag, struct proc *p) -</code> - -d_ioctl() is a catch-all for operations which don't make sense in -a read/write paradigm. Probably the most famous of all ioctl's is on -tty devices, through -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?stty(1)" name="stty(1)">. -The ioctl entry point is called from -ioctl() in sys/kern/sys_generic.c<p> - -There are four different types of ioctl's which can be implemented. -<sys/ioccom.h> contains convenience macros for defining these ioctls. - -<tt/_IO(g,n)/ for control type operations. &nl; - -<tt/_IOR(g,n,t)/ for operations that read data from a device. &nl; - -<tt/_IOW(g,n,t)/ for operations that write data to a device. &nl; - -<tt/_IOWR(g,n,t)/ for operations that write to a device, and then -read data back. &nl; - -Here <tt/g/ refers to a <em/group/. This is an 8-bit value, typically -indicative of the device; for example, 't' is used in tty ioctls. -<tt/n/ refers to the number of the ioctl within the group. On SCO, this -number alone denotes the ioctl. <tt/t/ is the data type which will -get passed to the driver; this gets handed to a sizeof() operator in -the kernel. The ioctl() system call will either copyin() or copyout() -or both for your driver, then hand you a pointer to the data structure -in the <tt/arg/ argument of the d_ioctl call. Currently the data size -is limited to one page (4k on the i386). - -<sect3> d_stop() -<sect3> d_reset() -<sect3> d_devtotty() -<sect3> d_poll() (3.0+) or d_select() (2.2) -<p> -d_poll()'s argument list is as follows: -<code> -void -d_poll(dev_t dev, int events, struct proc *p) -</code> - -<p> d_poll() is used to find out if a device is ready for IO. An -example is waiting for data to become available from the network, or -waiting for the user to press a key. This correspond to the poll() -call in userland. - -<p>The d_poll() call should check for the events specified in the -event mask. If none of the requested events are active, but they may -become active later, it should record this for the kernel's later -persual. d_poll() does this by calling selrecord() with a selinfo -structure for this device. The sum of all these activities look -something like this: - -<code> -static struct my_softc { - struct queue rx_queue; /* As example only - not required */ - struct queue tx_queue; /* As example only - not required */ - struct selinfo selp; /* Required */ -} my_softc[NMYDEV]; - -... - -static int -mydevpoll(dev_t dev, int events, struct proc *p) -{ - int revents = 0; /* Events we found */ - int s; - struct my_softc *sc = &my_softc[dev]; - - /* We can only check for IN and OUT */ - if ((events & (POLLIN|POLLOUT)) == 0) - return(POLLNVAL); - - s = splhigh(); - /* Writes are if the transmit queue can take them */ - if ((events & POLLOUT) && - !IF_QFULL(sc->tx_queue)) - revents |= POLLOUT; - /* ... while reads are OK if we have any data */ - if ((events & POLLIN) && - !IF_QEMPTY(sc->rx_queue)) - revents |= POLLIN; - if (revents == 0) - selrecord(p, &sc->selp); - splx(s); - return revents; -} -</code> - -<p> -d_select() is used in 2.2 and previous versions of FreeBSD. Instead -of 'events' it take a single int 'rw', which can be FREAD for reads -(as in POLLIN above), FWRITE for write (as in POLLOUT above), and 0 -for 'exception' - something exceptional happened, like a card being -inserted or removed for the pccard driver. - -<p>For select, the above code fragment would look like this: -<code> -static int -mydevselect(dev_t dev, int rw, struct proc *p) -{ - int ret = 0; - int s; - struct my_softc *sc = &my_softc[dev]; - - s = splhigh(); - switch (rw) { - case FWRITE: - /* Writes are if the transmit queue can take them */ - if (!IF_QFULL(sc->tx_queue)) - ret = 1; - break; - case FREAD: - /* ... while reads are OK if we have any data */ - if (!IF_QEMPTY(sc->rx_queue)) - ret = 1; - break; - case 0: - /* This driver never get any exceptions */ - break; - } - if(ret == 0) - selrecord(p, &sc->selp); - splx(s); - return(revents); -} -</code> - -<sect3> d_mmap() -<sect3> d_strategy() -<p> -d_strategy()'s argument list is as follows: -<code> -void -d_strategy(struct buf *bp) -</code> - -<p> d_strategy() is used for devices which use some form of scatter-gather -io. It is most common in a block device. This is significantly different -than the System V model, where only the block driver performs scatter-gather -io. Under BSD, character devices are sometimes requested to perform -scatter-gather io via the readv() and writev() system calls. - -<sect2> Header Files - -<sect1> Block -<sect2> Data Structures -<p> <tt/struct bdevsw/ Structure -<p> <tt/struct buf/ Structure - -<sect2> Entry Points -<sect3> d_open() -<p> Described in the Character device section. - -<sect3> d_close() -<p> Described in the Character device section. - -<sect3> d_strategy() -<p> Described in the Character device section. - -<sect3> d_ioctl() -<p> Described in the Character device section. - -<sect3> d_dump() - -<sect3> d_psize() - -<sect2> Header Files - -<sect1> Network -<sect2> Data Structures -<p> <tt/struct ifnet/ Structure - -<sect2> Entry Points -<sect3> if_init() -<sect3> if_output() -<sect3> if_start() -<sect3> if_done() -<sect3> if_ioctl() -<sect3> if_watchdog() - -<sect2> Header Files - -<sect1> Line Discipline -<sect2> Data Structures - -<p> <tt/struct linesw/ Structure - -<sect2> Entry Points -<sect3> l_open() -<sect3> l_close() -<sect3> l_read() -<sect3> l_write() -<sect3> l_ioctl() -<sect3> l_rint() -<sect3> l_start() -<sect3> l_modem() - -<sect2> Header Files - -<sect> Supported Busses - -<sect1> ISA -- Industry Standard Architecture -<sect2> Data Structures - -<sect3> <tt/struct isa_device/ Structure -<p> -This structure is required, but generally it is created by -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -from the kernel configuration file. It is required on a per-device -basis, meaning that if you have a driver which controls two serial -boards, you will have two isa_device structures. If you build a -device as an LKM, you must create your own isa_device structure to -reflect your configuration. (lines 85 - 131 in pcaudio_lkm.c) There is -nearly a direct mapping between the config file and the isa_device -structure. The definition from /usr/src/sys/i386/isa/isa_device.h is: -<code> -struct isa_device { - int id_id; /* device id */ - struct isa_driver *id_driver; - int id_iobase; /* base i/o address */ - u_short id_irq; /* interrupt request */ - short id_drq; /* DMA request */ - caddr_t id_maddr; /* physical i/o memory address on bus (if any)*/ - int id_msize; /* size of i/o memory */ - inthand2_t *id_intr; /* interrupt interface routine */ - int id_unit; /* unit number */ - int id_flags; /* flags */ - int id_scsiid; /* scsi id if needed */ - int id_alive; /* device is present */ -#define RI_FAST 1 /* fast interrupt handler */ - u_int id_ri_flags; /* flags for register_intr() */ - int id_reconfig; /* hot eject device support (such as PCMCIA) */ - int id_enabled; /* is device enabled */ - int id_conflicts; /* we're allowed to conflict with things */ - struct isa_device *id_next; /* used in isa_devlist in userconfig() */ -}; -</code> - -<!-- XXX add stuff here --> -<sect3> <tt/struct isa_driver/ Structure - -<p> -This structure is defined in ``/usr/src/sys/i386/isa/isa_device.h''. -These are required on a per-driver basis. The definition is: -<code> -struct isa_driver { - int (*probe) __P((struct isa_device *idp)); - /* test whether device is present */ - int (*attach) __P((struct isa_device *idp)); - /* setup driver for a device */ - char *name; /* device name */ - int sensitive_hw; /* true if other probes confuse us */ -}; -</code> - -This is the structure used by the probe/attach code to detect and -initialize your device. The <tt/probe/ member is a pointer to your -device probe function; the <tt/attach/ member is a pointer to your -attach function. The <tt/name/ member is a character pointer to the -two or three letter name for your driver. This is the name reported -during the probe/attach process (and probably also in -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?lsdev(8)" name="lsdev(8)">). The -<tt/sensitive_hw/ member is a flag which helps the probe code -determine probing order. - -A typical instantiation is: -<code> -struct isa_driver mcddriver = { mcd_probe, mcd_attach, "mcd" }; -</code> - -<sect2> Entry Points - -<sect3> probe() -<p> -probe() takes a <tt/struct isa_device/ pointer as an argument and returns -an int. The return value is ``zero'' or ``non-zero'' as to the absence -or presence of your device. This entry point may (and probably should) -be declared as <tt/static/ because it is accessed via the <tt/probe/ member -of the <tt/struct isa_driver/ structure. This function is intended -to detect the presence of your device only; it should not do any -configuration of the device itself. - -<sect3> attach() -<p> -attach() also takes a <tt/struct isa_device/ pointer as an argument and -returns an int. The return value is also ``zero'' or ``non-zero'' indicating -whether or not the attach was successful. This function is intended -to do any special initialization of the device as well as confirm that -the device is usable. It too should be declared <tt/static/ because -it is accessed through the <tt/attach/ member of the <tt/isa_driver/ -structure. - -<sect2> Header Files - -<sect1> EISA -- Extended Industry Standard Architecture - -<sect2> Data Structures - -<p> <tt/struct eisa_dev/ Structure -<p> <tt/struct isa_driver/ Structure - -<sect2> Entry Points - -<sect3> probe() -<p> Described in the ISA device section. - -<sect3> attach() -<p> Described in the ISA device section. - -<sect2> Header Files - -<sect1> PCI -- Peripheral Computer Interconnect -<sect2> Data Structures - -<p> <tt/struct pci_device/ Structure - - name: The short device name. - - probe: Checks if the driver can support a device - with this type. The tag may be used to get - more info with pci_read_conf(). See below. - It returns a string with the device's name, - or a NULL pointer, if the driver cannot - support this device. - - attach: Allocate a control structure and prepare - it. This function may use the PCI mapping - functions. See below. - (configuration id) or type. - - count: A pointer to a unit counter. - It's used by the PCI configurator to - allocate unit numbers. - -<sect2> Entry Points - -<sect3> probe() - -<sect3> attach() - -<sect3> shutdown() - -<sect2> Header Files - -<sect1> SCSI -- Small Computer Systems Interface -<sect2> Data Structures - -<p> <tt/struct scsi_adapter/ Structure -<p> <tt/struct scsi_device/ Structure -<p> <tt/struct scsi_ctlr_config/ Structure -<p> <tt/struct scsi_device_config/ Structure -<p> <tt/struct scsi_link/ Structure - -<sect2> Entry Points -<sect3> attach() -<sect3> init() - -<sect2> Header Files - -<sect1> PCCARD (PCMCIA) -<sect2> Data Structures -<p> <tt/struct slot_cont/ Structure -<p> <tt/struct pccard_drv/ Structure -<p> <tt/struct pccard_dev/ Structure -<p> <tt/struct slot/ Structure - -<sect2> Entry Points -<sect3> handler() -<sect3> unload() -<sect3> suspend() -<sect3> init() - -<sect2> Header Files - a. <pccard/slot.h> - -<sect> Linking Into the Kernel. - -<p> -In FreeBSD, support for the ISA and EISA busses is i386 specific. -While FreeBSD itself is presently available on the i386 platform, -some effort has been made to make the PCI, PCCARD, and SCSI code -portable. The ISA and EISA specific code resides in -/usr/src/sys/i386/isa and /usr/src/sys/i386/eisa respectively. -The machine independent PCI, PCCARD, and SCSI code reside in -/usr/src/sys/{pci,pccard,scsi}. The i386 specific code for these -reside in /usr/src/sys/i386/{pci,pccard,scsi}. - -<p> -In FreeBSD, a device driver can be either binary or source. There is -no ``official'' place for binary drivers to reside. BSD/OS uses -something like sys/i386/OBJ. Since most drivers are distributed -in source, the following discussion refers to a source driver. -Binary only drivers are sometimes provided by hardware vendors -who wish to maintain the source as proprietary. - -<p> -A typical driver has the source code in one c-file, say dev.c. The -driver also can have some include files; devreg.h typically contains -public device register declarations, macros, and other driver -specific declarations. Some drivers call this devvar.h instead. -Some drivers, such as the dgb (for the Digiboard PC/Xe), -require microcode to be loaded onto the board. For the dgb driver -the microcode is compiled and dumped into a header file ala -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?file2c(1)" name="file2c(1)">. - -<p> -If the driver has data structures and ioctl's which are specific to -the driver/device, and need to be accessible from user-space, they -should be put in a separate include file which will reside in -/usr/include/machine/ (some of these reside in /usr/include/sys/). -These are typically named something like ioctl_dev.h or devio.h. - -<p> -If a driver is being written which, from user space is -identical to a device which already exists, care should be taken to -use the same ioctl interface and data structures. For example, from -user space, a SCSI CDROM drive should be identical to an IDE cdrom -drive; or a serial line on an intelligent multiport card (Digiboard, -Cyclades, ...) should be identical to the sio devices. These devices -have a fairly well defined interface which should be used. - -<p> -There are two methods for linking a driver into the kernel, static and -the LKM model. The first method is fairly standard across the -*BSD family. The other method was originally developed by Sun -(I believe), and has been implemented into BSD using the Sun model. -I don't believe that the current implementation uses any Sun code. - -<sect1> Standard Model - -<p> -The steps required to add your driver to the standard FreeBSD kernel are -<itemize> -<item> Add to the driver list -<item> Add an entry to the [bc]devsw -<item> Add the driver entry to the kernel config file -<item> <htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)">, -compile, and install the kernel -<item> make required nodes. -<item> reboot. -</itemize> - -<sect2> Adding to the driver list. -<p> -The standard model for adding a device driver to the Berkeley kernel -is to add your driver to the list of known devices. This list is -dependent on the CPU architecture. If the device is not i386 specific -(PCCARD, PCI, SCSI), the file is in ``/usr/src/sys/conf/files''. -If the device is i386 specific, use ``/usr/src/sys/i386/conf/files.i386''. -A typical line looks like: -<tscreen><code> -i386/isa/joy.c optional joy device-driver -</code></tscreen> - -The first field is the pathname of the driver module relative to -/usr/src/sys. For the case of a binary driver the path would be -something like ``i386/OBJ/joy.o''. - -The second field tells -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -that this is an optional driver. Some -devices are required for the kernel to even be built. - -The third field is the name of the device. - -The fourth field tells config that it's a device driver (as opposed to -just optional). This causes config to create entries for the device -in some structures in /usr/src/sys/compile/KERNEL/ioconf.c. - -It is also possible to create a file -``/usr/src/sys/i386/conf/files.KERNEL'' whose contents will override -the default files.i386, but only for the kernel ``KERNEL''. - -<sect2>Make room in conf.c -<p> -Now you must edit ``/usr/src/sys/i386/i386/conf.c'' to make an entry -for your driver. Somewhere near the top, you need to declare your -entry points. The entry for the joystick driver is: -<code> -#include "joy.h" -#if NJOY > 0 -d_open_t joyopen; -d_close_t joyclose; -d_rdwr_t joyread; -d_ioctl_t joyioctl; -#else -#define joyopen nxopen -#define joyclose nxclose -#define joyread nxread -#define joyioctl nxioctl -#endif -</code> - -This either defines your entry points, or null entry points which -will return ENXIO when called (the #else clause). - -The include file ``joy.h'' is automatically generated by -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> when -the kernel build tree is created. This usually has only one line like: -<code> -#define NJOY 1 -</code> -or -<code> -#define NJOY 0 -</code> -which defines the number of your devices in your kernel. - -You must additionally add a slot to either cdevsw[&rsqb, or to -bdevsw[&rsqb, depending on whether it is a character device or -a block device, or both if it is a block device with a raw interface. -The entry for the joystick driver is: - -<code> -/* open, close, read, write, ioctl, stop, reset, ttys, select, mmap, strat */ -struct cdevsw cdevsw[] = -{ - ... - { joyopen, joyclose, joyread, nowrite, /*51*/ - joyioctl, nostop, nullreset, nodevtotty,/*joystick */ - seltrue, nommap, NULL}, - ... -} -</code> - -Order is what determines the major number of your device. Which is why -there will always be an entry for your driver, either null entry -points, or actual entry points. It is probably worth noting that this -is significantly different from SCO and other system V derivatives, -where any device can (in theory) have any major number. This is -largely a convenience on FreeBSD, due to the way device nodes are -created. More on this later. - -<sect2>Adding your device to the config file. -<p> -This is simply adding a line describing your device. -The joystick description line is: -<verb> -device joy0 at isa? port "IO_GAME" -</verb> -This says we have a device called ``joy0'' on the isa bus using -io-port ``IO_GAME'' (IO_GAME is a macro defined in -/usr/src/sys/i386/isa/isa.h). - -A slightly more complicated entry is for the ``ix'' driver: -<verb> -device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr -</verb> -This says that we have a device called `ix0' on the ISA bus. It uses -io-port 0x300. It's interrupt will be masked with other devices in -the network class. It uses interrupt 10. It uses -32k of shared memory at physical address 0xd0000. It also defines -it's interrupt handler to be ``ixintr()'' - -<sect2><htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -the kernel. -<p> -Now with our config file in hand, we can create a kernel compile directory. -This is done by simply typing: -<verb> -# config KERNEL -</verb> -where KERNEL is the name of your config file. Config creates a -compile tree for you kernel in /usr/src/sys/compile/KERNEL. It -creates the Makefile, some .c files, and some .h files with macros -defining the number of each device in your kernel. - -Now you can go to the compile directory and build. Each time you run -config, your previous build tree will be removed, unless you config -with a -n. If you have config'ed and compiled a GENERIC kernel, you can -``make links'' to avoid compiling a few files on each iteration. I typically -run -<verb> -# make depend links all -</verb> -followed by a ``make install'' when the kernel is done to my liking. - -<sect2>Making device nodes. -<p> -On FreeBSD, you are responsible for making your own device nodes. The -major number of your device is determined by the slot number in the -device switch. Minor number is driver dependent, of course. You can -either run the mknod's from the command line, or add a section to -/dev/MAKEDEV.local, or even /dev/MAKEDEV to do the work. I sometimes -create a MAKEDEV.dev script that can be run stand-alone or pasted -into /dev/MAKEDEV.local - -<sect2>Reboot. -<p> -This is the easy part. There are a number of ways to do this, reboot, -fastboot, shutdown -r, cycle the power, etc. Upon bootup you should -see your XXprobe() called, and if all is successful, your XXattach() -too. - -<sect1> Loadable Kernel Module (LKM) - -<p> -There are really no defined procedures for writing an LKM driver. The -following is my own conception after experimenting with the LKM device -interface and looking at the standard device driver model, this is one -way of adding an LKM interface to an existing driver without touching -the original driver source (or binary). It is recommended though, -that if you plan to release source to your driver, the LKM specific -parts should be part of the driver itself, conditionally compiled -on the LKM macro (i.e. #ifdef LKM). - -This section will focus on writing the LKM specific part of the driver. We -will assume that we have written a driver which will drop into the standard -device driver model, which we would now like to implement as an LKM. We will -use the pcaudio driver as a sample driver, and develop an LKM front-end. The -source and makefile for the pcaudio LKM, ``pcaudio_lkm.c'' and ``Makefile'', -should be placed in /usr/src/lkm/pcaudio. What follows is a breakdown of -pcaudio_lkm.c. - -Lines 17 - 26 - - -- This includes the file ``pca.h'' and conditionally compiles the rest -of the LKM on whether or not we have a pcaudio device defined. This -mimics the behavior of config. In a standard device driver, -<htmlurl url="http://www.freebsd.org/cgi/man.cgi?config(8)" name="config(8)"> -generates the pca.h file from the number pca devices in the config file. -<code> - 17 /* - 18 * figure out how many devices we have.. - 19 */ - 20 - 21 #include "pca.h" - 22 - 23 /* - 24 * if we have at least one ... - 25 */ - 26 #if NPCA > 0 -</code> - -Lines 27 - 37 - - -- Includes required files from various include directories. -<code> - 27 #include <sys/param.h> - 28 #include <sys/systm.h> - 29 #include <sys/exec.h> - 30 #include <sys/conf.h> - 31 #include <sys/sysent.h> - 32 #include <sys/lkm.h> - 33 #include <sys/errno.h> - 34 #include <i386/isa/isa_device.h> - 35 #include <i386/isa/isa.h> - 36 - 37 -</code> - -Lines 38 - 51 - - -- Declares the device driver entry points as external. -<code> - 38 /* - 39 * declare your entry points as externs - 40 */ - 41 - 42 extern int pcaprobe(struct isa_device *); - 43 extern int pcaattach(struct isa_device *); - 44 extern int pcaopen(dev_t, int, int, struct proc *); - 45 extern int pcaclose(dev_t, int, int, struct proc *); - 46 extern int pcawrite(dev_t, struct uio *, int); - 47 extern int pcaioctl(dev_t, int, caddr_t); - 48 extern int pcaselect(dev_t, int, struct proc *); - 49 extern void pcaintr(struct clockframe *); - 50 extern struct isa_driver pcadriver; - 51 -</code> - -Lines 52 - 70 - - -- This is creates the device switch entry table for your driver. -This table gets swapped wholesale into the system device switch at -the location specified by your major number. In the standard model, -these are in /usr/src/sys/i386/i386/conf.c. NOTE: you cannot pick a -device major number higher than what exists in conf.c, for example at -present, conf.c rev 1.85, there are 67 slots for character devices, -you cannot use a (character) major device number 67 or greater, -without first reserving space in conf.c. -<code> - 52 /* - 53 * build your device switch entry table - 54 */ - 55 - 56 static struct cdevsw pcacdevsw = { - 57 (d_open_t *) pcaopen, /* open */ - 58 (d_close_t *) pcaclose, /* close */ - 59 (d_rdwr_t *) enodev, /* read */ - 60 (d_rdwr_t *) pcawrite, /* write */ - 61 (d_ioctl_t *) pcaioctl, /* ioctl */ - 62 (d_stop_t *) enodev, /* stop?? */ - 63 (d_reset_t *) enodev, /* reset */ - 64 (d_ttycv_t *) enodev, /* ttys */ - 65 (d_select_t *) pcaselect, /* select */ - 66 (d_mmap_t *) enodev, /* mmap */ - 67 (d_strategy_t *) enodev /* strategy */ - 68 }; - 69 - 70 -</code> - -Lines 71 - 131 - - -- This section is analogous to the config file declaration of your -device. The members of the isa_device structure are filled in by what -is known about your device, I/O port, shared memory segment, etc. We -will probably never have a need for two pcaudio devices in the kernel, -but this example shows how multiple devices can be supported. -<code> - 71 /* - 72 * this lkm arbitrarily supports two - 73 * instantiations of the pc-audio device. - 74 * - 75 * this is for illustration purposes - 76 * only, it doesn't make much sense - 77 * to have two of these beasts... - 78 */ - 79 - 80 - 81 /* - 82 * these have a direct correlation to the - 83 * config file entries... - 84 */ - 85 struct isa_device pcadev[NPCA] = { - 86 { - 87 11, /* device id */ - 88 &pcadriver, /* driver pointer */ - 89 IO_TIMER1, /* base io address */ - 90 -1, /* interrupt */ - 91 -1, /* dma channel */ - 92 (caddr_t)-1, /* physical io memory */ - 93 0, /* size of io memory */ - 94 pcaintr , /* interrupt interface */ - 95 0, /* unit number */ - 96 0, /* flags */ - 97 0, /* scsi id */ - 98 0, /* is alive */ - 99 0, /* flags for register_intr */ - 100 0, /* hot eject device support */ - 101 1 /* is device enabled */ - 102 }, - 103 #if NPCA >1 - 104 { - 105 - 106 /* - 107 * these are all zeros, because it doesn't make - 108 * much sense to be here - 109 * but it may make sense for your device - 110 */ - 111 - 112 0, /* device id */ - 113 &pcadriver, /* driver pointer */ - 114 0, /* base io address */ - 115 -1, /* interrupt */ - 116 -1, /* dma channel */ - 117 -1, /* physical io memory */ - 118 0, /* size of io memory */ - 119 NULL, /* interrupt interface */ - 120 1, /* unit number */ - 121 0, /* flags */ - 122 0, /* scsi id */ - 123 0, /* is alive */ - 124 0, /* flags for register_intr */ - 125 0, /* hot eject device support */ - 126 1 /* is device enabled */ - 127 }, - 128 #endif - 129 - 130 }; - 131 -</code> - -Lines 132 - 139 - - -- This calls the C-preprocessor macro MOD_DEV, which sets up an LKM device -driver, as opposed to an LKM filesystem, or an LKM system call. -<code> - 132 /* - 133 * this macro maps to a function which - 134 * sets the LKM up for a driver - 135 * as opposed to a filesystem, system call, or misc - 136 * LKM. - 137 */ - 138 MOD_DEV("pcaudio_mod", LM_DT_CHAR, 24, &pcacdevsw); - 139 -</code> - -Lines 140 - 168 - - -- This is the function which will be called when the driver is -loaded. This function tries to work like sys/i386/isa/isa.c -which does the probe/attach calls for a driver at boot time. The -biggest trick here is that it maps the physical address of the shared -memory segment, which is specified in the isa_device structure to a -kernel virtual address. Normally the physical address is put in the -config file which builds the isa_device structures in -/usr/src/sys/compile/KERNEL/ioconf.c. The probe/attach sequence of -/usr/src/sys/isa/isa.c translates the physical address to a virtual -one so that in your probe/attach routines you can do things like -<verb> -(int *)id->id_maddr = something; -</verb> -and just refer to the shared memory segment via pointers. -<code> - 140 /* - 141 * this function is called when the module is - 142 * loaded; it tries to mimic the behavior - 143 * of the standard probe/attach stuff from - 144 * isa.c - 145 */ - 146 int - 147 pcaload(){ - 148 int i; - 149 uprintf("PC Audio Driver Loaded\n"); - 150 for (i=0; i<NPCA; i++){ - 151 /* - 152 * this maps the shared memory address - 153 * from physical to virtual, to be - 154 * consistent with the way - 155 * /usr/src/sys/i386/isa.c handles it. - 156 */ - 157 pcadev[i].id_maddr -=0xa0000; - 158 pcadev[i].id_maddr += atdevbase; - 159 if ((*pcadriver.probe)(pcadev+i)) { - 160 (*(pcadriver.attach))(pcadev+i); - 161 } else { - 162 uprintf("PC Audio Probe Failed\n"); - 163 return(1); - 164 } - 165 } - 166 return 0; - 167 } - 168 -</code> - -Lines 169 - 179 - - -- This is the function called when your driver is unloaded; it just displays -a message to that effect. -<code> - 169 /* - 170 * this function is called - 171 * when the module is unloaded - 172 */ - 173 - 174 int - 175 pcaunload(){ - 176 uprintf("PC Audio Driver Unloaded\n"); - 177 return 0; - 178 } - 179 -</code> - -Lines 180 - 190 - - -- This is the entry point which is specified on the command line of the -modload. By convention it is named <dev>_mod. This is how it is -defined in bsd.lkm.mk, the makefile which builds the LKM. If you name your -module following this convention, you can do ``make load'' and ``make -unload'' from /usr/src/lkm/pcaudio. <p> -Note: this has gone through <em/many/ revisions from release 2.0 to 2.1. -It may or may not be possible to write a module which is portable across -all three releases. <p> -<code> - 180 /* - 181 * this is the entry point specified - 182 * on the modload command line - 183 */ - 184 - 185 int - 186 pcaudio_mod(struct lkm_table *lkmtp, int cmd, int ver) - 187 { - 188 DISPATCH(lkmtp, cmd, ver, pcaload, pcaunload, nosys); - 189 } - 190 - 191 #endif /* NICP > 0 */ -</code> - -<sect1> Device Type Idiosyncrasies -<sect2> Character -<sect2> Block -<sect2> Network -<sect2> Line Discipline - -<sect1> Bus Type Idiosyncrasies -<sect2> ISA -<sect2> EISA -<sect2> PCI -<sect2> SCSI -<sect2> PCCARD - -<sect> Kernel Support - -<sect1> Data Structures - -<sect2> <tt/struct kern_devconf/ Structure -<p> - -This structure contains some information about the state of the device -and driver. It is defined in /usr/src/sys/sys/devconf.h as: -<code> -struct devconf { - char dc_name[MAXDEVNAME]; /* name */ - char dc_descr[MAXDEVDESCR]; /* description */ - int dc_unit; /* unit number */ - int dc_number; /* unique id */ - char dc_pname[MAXDEVNAME]; /* name of the parent device */ - int dc_punit; /* unit number of the parent */ - int dc_pnumber; /* unique id of the parent */ - struct machdep_devconf dc_md; /* machine-dependent stuff */ - enum dc_state dc_state; /* state of the device (see above) */ - enum dc_class dc_class; /* type of device (see above) */ - size_t dc_datalen; /* length of data */ - char dc_data[1]; /* variable-length data */ -}; -</code> - -<sect2> <tt/struct proc/ Structure -<p> - -This structure contains all the information about a process. -It is defined in /usr/src/sys/sys/proc.h: -<code> -/* - * Description of a process. - * - * This structure contains the information needed to manage a thread of - * control, known in UN*X as a process; it has references to substructures - * containing descriptions of things that the process uses, but may share - * with related processes. The process structure and the substructures - * are always addressable except for those marked "(PROC ONLY)" below, - * which might be addressable only on a processor on which the process - * is running. - */ -struct proc { - struct proc *p_forw; /* Doubly-linked run/sleep queue. */ - struct proc *p_back; - struct proc *p_next; /* Linked list of active procs */ - struct proc **p_prev; /* and zombies. */ - - /* substructures: */ - struct pcred *p_cred; /* Process owner's identity. */ - struct filedesc *p_fd; /* Ptr to open files structure. */ - struct pstats *p_stats; /* Accounting/statistics (PROC ONLY). */ struct plimit *p_limit; /* Process limits. */ - struct vmspace *p_vmspace; /* Address space. */ - struct sigacts *p_sigacts; /* Signal actions, state (PROC ONLY). */ - -#define p_ucred p_cred->pc_ucred -#define p_rlimit p_limit->pl_rlimit - - int p_flag; /* P_* flags. */ - char p_stat; /* S* process status. */ - char p_pad1[3]; - - pid_t p_pid; /* Process identifier. */ - struct proc *p_hash; /* Hashed based on p_pid for kill+exit+... */ - struct proc *p_pgrpnxt; /* Pointer to next process in process group. */ - struct proc *p_pptr; /* Pointer to process structure of parent. */ - struct proc *p_osptr; /* Pointer to older sibling processes. */ - -/* The following fields are all zeroed upon creation in fork. */ -#define p_startzero p_ysptr - struct proc *p_ysptr; /* Pointer to younger siblings. */ - struct proc *p_cptr; /* Pointer to youngest living child. */ - pid_t p_oppid; /* Save parent pid during ptrace. XXX */ - int p_dupfd; /* Sideways return value from fdopen. XXX */ - - /* scheduling */ - u_int p_estcpu; /* Time averaged value of p_cpticks. */ - int p_cpticks; /* Ticks of cpu time. */ - fixpt_t p_pctcpu; /* %cpu for this process during p_swtime */ - void *p_wchan; /* Sleep address. */ - char *p_wmesg; /* Reason for sleep. */ - u_int p_swtime; /* Time swapped in or out. */ - u_int p_slptime; /* Time since last blocked. */ - - struct itimerval p_realtimer; /* Alarm timer. */ - struct timeval p_rtime; /* Real time. */ - u_quad_t p_uticks; /* Statclock hits in user mode. */ - u_quad_t p_sticks; /* Statclock hits in system mode. */ - u_quad_t p_iticks; /* Statclock hits processing intr. */ - - int p_traceflag; /* Kernel trace points. */ - struct vnode *p_tracep; /* Trace to vnode. */ - - int p_siglist; /* Signals arrived but not delivered. */ - - struct vnode *p_textvp; /* Vnode of executable. */ - - char p_lock; /* Process lock (prevent swap) count. */ - char p_pad2[3]; /* alignment */ - -/* End area that is zeroed on creation. */ -#define p_endzero p_startcopy - -/* The following fields are all copied upon creation in fork. */ -#define p_startcopy p_sigmask - - sigset_t p_sigmask; /* Current signal mask. */ - sigset_t p_sigignore; /* Signals being ignored. */ - sigset_t p_sigcatch; /* Signals being caught by user. */ - - u_char p_priority; /* Process priority. */ - u_char p_usrpri; /* User-priority based on p_cpu and p_nice. */ - char p_nice; /* Process "nice" value. */ - char p_comm[MAXCOMLEN+1]; - - struct pgrp *p_pgrp; /* Pointer to process group. */ - - struct sysentvec *p_sysent; /* System call dispatch information. */ - - struct rtprio p_rtprio; /* Realtime priority. */ -/* End area that is copied on creation. */ -#define p_endcopy p_addr - struct user *p_addr; /* Kernel virtual addr of u-area (PROC ONLY). */ - struct mdproc p_md; /* Any machine-dependent fields. */ - - u_short p_xstat; /* Exit status for wait; also stop signal. */ - u_short p_acflag; /* Accounting flags. */ - struct rusage *p_ru; /* Exit information. XXX */ -}; -</code> - -<sect2> <tt/struct buf/ Structure -<p> -The <tt/struct buf/ structure is used to interface with the buffer cache. -It is defined in /usr/src/sys/sys/buf.h: - -<code> -/* - * The buffer header describes an I/O operation in the kernel. - */ -struct buf { - LIST_ENTRY(buf) b_hash; /* Hash chain. */ - LIST_ENTRY(buf) b_vnbufs; /* Buffer's associated vnode. */ - TAILQ_ENTRY(buf) b_freelist; /* Free list position if not active. */ - struct buf *b_actf, **b_actb; /* Device driver queue when active. */ - struct proc *b_proc; /* Associated proc; NULL if kernel. */ - volatile long b_flags; /* B_* flags. */ - int b_qindex; /* buffer queue index */ - int b_error; /* Errno value. */ - long b_bufsize; /* Allocated buffer size. */ - long b_bcount; /* Valid bytes in buffer. */ - long b_resid; /* Remaining I/O. */ - dev_t b_dev; /* Device associated with buffer. */ - struct { - caddr_t b_addr; /* Memory, superblocks, indirect etc. */ - } b_un; - void *b_saveaddr; /* Original b_addr for physio. */ - daddr_t b_lblkno; /* Logical block number. */ - daddr_t b_blkno; /* Underlying physical block number. */ - /* Function to call upon completion. */ - void (*b_iodone) __P((struct buf *)); - /* For nested b_iodone's. */ - struct iodone_chain *b_iodone_chain; - struct vnode *b_vp; /* Device vnode. */ - int b_pfcent; /* Center page when swapping cluster. */ - int b_dirtyoff; /* Offset in buffer of dirty region. */ - int b_dirtyend; /* Offset of end of dirty region. */ - struct ucred *b_rcred; /* Read credentials reference. */ - struct ucred *b_wcred; /* Write credentials reference. */ - int b_validoff; /* Offset in buffer of valid region. */ - int b_validend; /* Offset of end of valid region. */ - daddr_t b_pblkno; /* physical block number */ - caddr_t b_savekva; /* saved kva for transfer while bouncing - */ - void *b_driver1; /* for private use by the driver */ - void *b_driver2; /* for private use by the driver */ - void *b_spc; - struct vm_page *b_pages[(MAXPHYS + PAGE_SIZE - 1)/PAGE_SIZE]; - int b_npages; -}; -</code> - -<sect2> <tt/struct uio/ Structure -<p> -This structure is used for moving data between the kernel and user spaces -through read() and write() system calls. It is defined in -/usr/src/sys/sys/uio.h: -<code> -struct uio { - struct iovec *uio_iov; - int uio_iovcnt; - off_t uio_offset; - int uio_resid; - enum uio_seg uio_segflg; - enum uio_rw uio_rw; - struct proc *uio_procp; -}; - -</code> - -<sect1> Functions -lots of 'em - -<sect> References. - -<p> FreeBSD Kernel Sources http://www.freebsd.org -<p> NetBSD Kernel Sources http://www.netbsd.org -<p> Writing Device Drivers: Tutorial and Reference; -Tim Burke, Mark A. Parenti, Al, Wojtas; -Digital Press, ISBN 1-55558-141-2. - -<p> Writing A Unix Device Driver; -Janet I. Egan, Thomas J. Teixeira; -John Wiley & Sons, ISBN 0-471-62859-X. - -<p> Writing Device Drivers for SCO Unix; -Peter Kettle; - -</article> diff --git a/en/tutorials/devel/Makefile b/en/tutorials/devel/Makefile deleted file mode 100644 index 72c7507f01..0000000000 --- a/en/tutorials/devel/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:11 max Exp $ - -DOCS= devel.docb -INDEXLINK= devel.html - -.include "../../web.mk" - diff --git a/en/tutorials/devel/devel.docb b/en/tutorials/devel/devel.docb deleted file mode 100644 index 5d712bcab5..0000000000 --- a/en/tutorials/devel/devel.docb +++ /dev/null @@ -1,1835 +0,0 @@ -<!-- $Id: devel.docb,v 1.5 1999-03-21 16:16:17 wosch Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> -<bookinfo> -<bookbiblio> -<title>A User's Guide to FreeBSD Programming Tools</title> - -<authorgroup> -<author> -<firstname>James</firstname> -<surname>Raynard</surname> -<affiliation> -<address> -<email>jraynard@freebsd.org</email> -</address> -</affiliation> -</author></authorgroup> - -<pubdate>August 17, 1997</pubdate> - -<copyright> -<year>1997</year> -<holder>James Raynard</holder> -</copyright> - -<abstract><para>This document is an introduction to using some of the programming -tools supplied with FreeBSD, although much of it will be applicable to -many other versions of Unix. It does <emphasis>not</emphasis> attempt to describe -coding in any detail. Most of the document assumes little or no -previous programming knowledge, although it is hoped that most -programmers will find something of value in it</para></abstract> -</bookbiblio> -</bookinfo> - -<chapter> -<title>Introduction<anchor id=foo></title> - -<para>FreeBSD offers an excellent development environment. Compilers -for C, C++, and Fortran and an assembler come with the basic system, -not to mention a Perl interpreter and classic Unix tools such as -<command>sed</> and <command>awk</>. If that is not enough, there are -many more compilers and interpreters in the Ports collection. FreeBSD -is very compatible with standards such as <acronym>POSIX</> and -<acronym>ANSI</> C, as well with its own BSD heritage, so it is -possible to write applications that will compile and run with little -or no modification on a wide range of platforms.</para> - -<para>However, all this power can be rather overwhelming at first if -you've never written programs on a Unix platform before. This -document aims to help you get up and running, without getting too -deeply into more advanced topics. The intention is that this document -should give you enough of the basics to be able to make some sense of -the documentation.</para> - -<para>Most of the document requires little or no knowledge of -programming, although it does assume a basic competence with using -Unix and a willingness to learn!</para> - -</chapter> - -<chapter> -<title>Introduction to Programming</title> - -<para>A program is a set of instructions that tell the computer to do -various things; sometimes the instruction it has to perform depends -on what happened when it performed a previous instruction. This -section gives an overview of the two main ways in which you can give -these instructions, or <quote>commands</quote> as they are usually -called. One way uses an <firstterm>interpreter</>, the other a -<firstterm>compiler</>. As human languages are too difficult for a -computer to understand in an unambiguous way, commands are usually -written in one or other languages specially designed for the -purpose.</para> - - - -<sect1> -<title>Interpreters</title> - -<para>With an interpreter, the language comes as an environment, where you -type in commands at a prompt and the environment executes them for -you. For more complicated programs, you can type the commands into a -file and get the interpreter to load the file and execute the commands -in it. If anything goes wrong, many interpreters will drop you into a -debugger to help you track down the problem.</para> - -<para>The advantage of this is that you can see the results of your -commands immediately, and mistakes can be corrected readily. The -biggest disadvantage comes when you want to share your programs with -someone. They must have the same interpreter, or you must have some -way of giving it to them, and they need to understand how to use it. -Also users may not appreciate being thrown into a debugger if they -press the wrong key! From a performance point of view, interpreters -can use up a lot of memory, and generally do not generate code as -efficiently as compilers.</para> - -<para>In my opinion, interpreted languages are the best way to start -if you have not done any programming before. This kind of environment -is typically found with languages like Lisp, Smalltalk, Perl and -Basic. It could also be argued that the Unix shell (<command>sh</>, -<command>csh</>) is itself an interpreter, and many people do in fact -write shell <quote>scripts</quote> to help with various -<quote>housekeeping</> tasks on their machine. Indeed, part of the -original Unix philosophy was to provide lots of small utility -programs that could be linked together in shell scripts to perform -useful tasks.</para> - -</sect1> - -<sect1> -<title>Interpreters available with FreeBSD</title> - -<para>Here is a list of interpreters that are available as <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/">FreeBSD -packages</ulink>, with a brief discussion of some of the more popular -interpreted languages. </para> - -<para>To get one of these packages, all you need to do is to click on -the hotlink for the package, then run -<screen>$ <userinput>pkg_add <replaceable>package name</></userinput></screen> -</para> - -<para>as root. Obviously, you will need to have a fully functional FreeBSD -2.1.0 or later system for the package to work!</para> - -<para> -<variablelist> -<varlistentry><term><acronym>BASIC</></term> - -<listitem><para>Short for Beginner's All-purpose Symbolic Instruction -Code. Developed in the 1950s for teaching University students to -program and provided with every self-respecting personal computer in -the 1980s, <acronym>BASIC</> has been the first programming language -for many programmers. It's also the foundation for <trademark>Visual -Basic</>.</para> - -<para>The <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/bwbasic-2.10.tgz">Bywater -Basic Interpreter</ulink> and the <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/pbasic-2.0.tgz">Phil -Cockroft's Basic Interpreter</ulink> (formerly Rabbit Basic) are -available as FreeBSD <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/">FreeBSD -packages</ulink></para> -</listitem> -</varlistentry> - -<varlistentry><term>Lisp</term> -<listitem><para>A language that was developed in the late 1950s as an alternative to -the <quote>number-crunching</quote> languages that were popular at the time. -Instead of being based on numbers, Lisp is based on lists; in fact -the name is short for <quote>List Processing</quote>. Very popular in AI -(Artificial Intelligence) circles.</para> - -<para>Lisp is an extremely powerful and sophisticated language, but -can be rather large and unwieldy. </para> - -<para>FreeBSD has <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/gcl-2.0.tgz">GNU -Common Lisp</ulink> available as a package.</para> - -</listitem> -</varlistentry> - -<varlistentry><term>Perl</term> -<listitem><para>Very popular with system administrators for writing -scripts; also often used on World Wide Web servers for writing <acronym>CGI</> -scripts.</para> - -<para>Version 4, which is probably still the most widely-used -version, comes with FreeBSD; the newer <ulink -URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/perl-5.001.tgz">Perl -Version 5</ulink> is available as a package.</para> - -</listitem> -</varlistentry> - -<varlistentry><term>Scheme</term> -<listitem><para>A dialect of Lisp that is rather more compact and -cleaner than Common Lisp. Popular in Universities as it is simple -enough to teach to undergraduates as a first language, while it has a -high enough level of abstraction to be used in research work.</para> - -<para>FreeBSD has packages of the -<ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/elk-3.0.tgz">Elk Scheme Interpreter</ulink>, the -<ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/mit-scheme-7.3.tgz">MIT Scheme Interpreter</ulink> and the -<ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/scm-4e1.tgz">SCM Scheme Interpreter</ulink>.</para> - -</listitem> -</varlistentry> - -<varlistentry><term>Icon</term> -<listitem><para><ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/icon-9.0.tgz">The Icon Programming Language</ulink>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Logo</term> -<listitem><para><ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/ucblogo-3.3.tgz">Brian Harvey's LOGO Interpreter</ulink>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Python</term> -<listitem><para><ulink URL="ftp://ftp.freebsd.org:pub/FreeBSD/packages/lang/python-1.2">The Python Object-Oriented Programming Language</ulink></para> -</listitem> -</varlistentry> - -</variablelist> -</para> - -</sect1> - -<sect1> -<title>Compilers</title> - -<para>Compilers are rather different. First of all, you write your -code in a file (or files) using an editor. You then run the compiler -and see if it accepts your program. If it did not compile, grit your -teeth and go back to the editor; if it did compile and gave you a -program, you can run it either at a shell command prompt or in a -debugger to see if it works properly.<footnote><para>If you run it in -the shell, you may get a core dump.</para></footnote></para> - -<para>Obviously, this is not quite as direct as using an interpreter. -However it allows you to do a lot of things which are very difficult -or even impossible with an interpreter, such as writing code which -interacts closely with the operating system—or even writing -your own operating system! It's also useful if you need to write very -efficient code, as the compiler can take its time and optimise the -code, which would not be acceptable in an interpreter. And -distributing a program written for a compiler is usually more -straightforward than one written for an interpreter—you can just -give them a copy of the executable, assuming they have the same -operating system as you.</para> - -<para>Compiled languages include Pascal, C and C++. C and C++ are rather -unforgiving languages, and best suited to more experienced -programmers; Pascal, on the other hand, was designed as an educational -language, and is quite a good language to start with. Unfortunately, -FreeBSD doesn't have any Pascal support, except for a Pascal-to-C -converter in the ports.</para> - -<para>As the edit-compile-run-debug cycle is rather tedious when -using separate programs, many commercial compiler makers have -produced Integrated Development Environments (<acronym>IDE</acronym>s -for short). FreeBSD does not have an <acronym>IDE</> as such; however -it is possible to use Emacs for this purpose. This is discussed in -<xref linkend="emacs">.</para> - -</sect1> -</chapter> - -<chapter> -<title>Compiling with <command>cc</command></title> - -<para>This section deals only with the GNU compiler for C and C++, -since that comes with the base FreeBSD system. It can be invoked by -either <command>cc</> or <command>gcc</>. The details of producing a -program with an interpreter vary considerably between interpreters, -and are usually well covered in the documentation and on-line help -for the interpreter.</para> - -<para>Once you've written your masterpiece, the next step is to convert it -into something that will (hopefully!) run on FreeBSD. This usually -involves several steps, each of which is done by a separate -program.</para> - -<procedure> -<step><para>Pre-process your source code to remove comments and do other -tricks like expanding macros in C. -</para></step> - -<step><para>Check the syntax of your code to see if you have obeyed the -rules of the language. If you have not, it will complain! -</para></step> - -<step><para>Convert the source code into assembly -language—this is very close to machine code, but still -understandable by humans. Allegedly.<footnote><para>To be strictly -accurate, <command>cc</> converts the source code into its own, -machine-independent <firstterm>p-code</> instead of assembly language -at this stage.</para></footnote></para></step> - -<step><para>Convert the assembly language into machine -code—yep, we are talking bits and bytes, ones and zeros -here.</para></step> - -<step><para>Check that you have used things like functions and global -variables in a consistent way. For example, if you have called a -non-existent function, it will complain.</para></step> - -<step><para>If you are trying to produce an executable from several -source code files, work out how to fit them all together.</para></step> - -<step><para>Work out how to produce something that the system's run-time -loader will be able to load into memory and run.</para></step> - -<step><para>Finally, write the executable on the file -system.</para></step> - -</procedure> - -<para>The word <firstterm>compiling</> is often used to refer to just -steps 1 to 4—the others are referred to as -<firstterm>linking</>. Sometimes step 1 is referred to as -<firstterm>pre-processing</> and steps 3-4 as -<firstterm>assembling</>.</para> - -<para>Fortunately, almost all this detail is hidden from you, as -<command>cc</> is a front end that manages calling all these programs -with the right arguments for you; simply typing -<screen>$ <userinput>cc foobar.c</></screen></para> - -<para>will cause <filename>foobar.c</> to be compiled by all the -steps above. If you have more than one file to compile, just do -something like -<screen>$ <userinput>cc foo.c bar.c</></screen> -</para> - -<para>Note that the syntax checking is just that—checking the -syntax. It will not check for any logical mistakes you may have made, -like putting the program into an infinite loop, or using a bubble -sort when you meant to use a binary sort.<footnote><para>In case you -didn't know, a binary sort is an efficient way of sorting things into -order and a bubble sort isn't.</para></footnote></para> - -<para>There are lots and lots of options for <command>cc</>, which -are all in the man page. Here are a few of the most important ones, -with examples of how to use them.</para> - -<variablelist> -<varlistentry><term><option>-o <replaceable>filename</replaceable></></term> - -<listitem><para>The output name of the file. If you do not use this -option, <command>cc</> will produce an executable called -<filename>a.out</>.<footnote><para>The reasons for this are buried in -the mists of history.</para></footnote></para> - -<informalexample> -<screen>$ <userinput>cc foobar.c</> <lineannotation>executable is <filename>a.out</></> -$ <userinput>cc -o foobar foobar.c</> <lineannotation>executable is <filename>foobar</></></screen> -</informalexample> -</listitem> -</varlistentry> - -<varlistentry><term><option>-c</option></term> -<listitem><para>Just compile the file, do not link it. Useful for toy -programs where you just want to check the syntax, or if you are using -a <filename>Makefile</filename>.</para> - -<informalexample> -<screen>$ <userinput>cc -c foobar.c</userinput></screen> -</informalexample> - -<para>This will produce an <firstterm>object file</> (not an -executable) called <filename>foobar.o</filename>. This can be linked -together with other object files into an executable.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><option>-g</option></term> - -<listitem><para>Create a debug version of the executable. This makes -the compiler put information into the executable about which line of -which source file corresponds to which function call. A debugger can -use this information to show the source code as you step through the -program, which is <emphasis>very</emphasis> useful; the disadvantage -is that all this extra information makes the program much bigger. -Normally, you compile with <option>-g</option> while you are -developing a program and then compile a <quote>release -version</quote> without <option>-g</option> when you're satisfied it -works properly.</para> - -<informalexample> -<screen>$ <userinput>cc -g foobar.c</userinput></screen> -</informalexample> - -<para>This will produce a debug version of the -program.<footnote><para>Note, we didn't use the <option>-o</option> -flag to specify the executable name, so we will get an executable -called <filename>a.out</filename>. Producing a debug version called -<filename>foobar</filename> is left as an exercise for the -reader!</para></footnote></para> - -</listitem> -</varlistentry> - -<varlistentry><term><option>-O</option></term> - -<listitem><para>Create an optimised version of the executable. The -compiler performs various clever tricks to try and produce an -executable that runs faster than normal. You can add a number after -the <option>-O</option> to specify a higher level of optimisation, -but this often exposes bugs in the compiler's optimiser. For -instance, the version of <command>cc</command> that comes with the -2.1.0 release of FreeBSD is known to produce bad code with the -<option>-O2</option> option in some circumstances.</para> - -<para>Optimisation is usually only turned on when compiling a release -version.</para> - -<informalexample> -<screen>$ <userinput>cc -O -o foobar foobar.c</userinput></screen> -</informalexample> - -<para>This will produce an optimised version of -<filename>foobar</filename>.</para> - -</listitem> -</varlistentry> -</variablelist> - -<para>The following three flags will force <command>cc</command> to -check that your code complies to the relevant international standard, -often referred to as the <acronym>ANSI</acronym> standard, though -strictly speaking it is an <acronym>ISO</acronym> standard.</para> - -<variablelist> - -<varlistentry><term><option>-Wall</option></term> - -<listitem><para>Enable all the warnings which the authors of -<command>cc</command> believe are worthwhile. Despite the name, it -will not enable all the warnings <command>cc</command> is capable -of.</para></listitem> - -</varlistentry> - -<varlistentry><term><option>-ansi</option></term> - -<listitem> -<para>Turn off most, but not all, of the non-<acronym>ANSI</> C -features provided by <command>cc</command>. Despite the name, it does -not guarantee strictly that your code will comply to the -standard.</para> -</listitem> - -</varlistentry> - -<varlistentry><term><option>-pedantic</option></term> - -<listitem> -<para>Turn off <emphasis>all</emphasis> -<command>cc</command>'s non-<acronym>ANSI</> C features.</para> -</listitem> - -</varlistentry> -</variablelist> - -<para>Without these flags, <command>cc</command> will allow you to -use some of its non-standard extensions to the standard. Some of -these are very useful, but will not work with other compilers—in -fact, one of the main aims of the standard is to allow people to -write code that will work with any compiler on any system. This is -known as <firstterm>portable code</firstterm>.</para> - -<para>Generally, you should try to make your code as portable as -possible, as otherwise you may have to completely re-write the -program later to get it to work somewhere else—and who knows -what you may be using in a few years time?</para> - -<informalexample> -<screen>$ <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput></screen> -</informalexample> - -<para>This will produce an executable <filename>foobar</filename> -after checking <filename>foobar.c</filename> for standard -compliance.</para> - -<variablelist> - -<varlistentry><term><option>-l<replaceable>library</replaceable></option></term> - -<listitem><para>Specify a function library to be used during when -linking.</para> - -<para>The most common example of this is when compiling a program that -uses some of the mathematical functions in C. Unlike most other -platforms, these are in a separate library from the standard C one -and you have to tell the compiler to add it.</para> - -<para>The rule is that if the library is called -<filename>lib<replaceable>something</replaceable>.a</filename>, you -give <command>cc</command> the argument -<option>-l<replaceable>something</replaceable></option>. For example, -the math library is <filename>libm.a</filename>, so you give -<command>cc</command> the argument <option>-lm</option>. A common -<quote>gotcha</quote> with the math library is that it has to be the -last library on the command line.</para> - -<informalexample> -<screen>$ <userinput>cc -o foobar foobar.c -lm</userinput></screen> -</informalexample> - -<para>This will link the math library functions into -<filename>foobar</filename>.</para> - -<para>If you are compiling C++ code, you need to add -<option>-lg++</option>, or <option>-lstdc++</option> if you are using -FreeBSD 2.2 or later, to the command line argument to link the C++ -library functions. Alternatively, you can run <command>c++</command> -instead of <command>cc</command>, which does this for you. -<command>c++</command> can also be invoked as <command>g++</command> -on FreeBSD.</para> - -<informalexample> -<screen>$ <userinput>cc -o foobar foobar.cc -lg++</userinput> <lineannotation>For FreeBSD 2.1.6 and earlier</> -$ <userinput>cc -o foobar foobar.cc -lstdc++</userinput> <lineannotation>For FreeBSD 2.2 and later</> -$ <userinput>c++ -o foobar foobar.cc</userinput></screen> -</informalexample> - -<para>Each of these will both produce an executable -<filename>foobar</filename> from the C++ source file -<filename>foobar.cc</filename>. Note that, on Unix systems, C++ -source files traditionally end in <filename>.C</filename>, -<filename>.cxx</filename> or <filename>.cc</filename>, rather than -the <trademark>MS-DOS</trademark> style <filename>.cpp</filename> -(which was already used for something else). <command>gcc</command> -used to rely on this to work out what kind of compiler to use on the -source file; however, this restriction no longer applies, so you may -now call your C++ files <filename>.cpp</filename> with -impunity!</para> - -</listitem> -</varlistentry> -</variablelist> - -<sect1> -<title>Common <command>cc</command> Queries and Problems</title> - -<para>Q. I am trying to write a program which uses the -<function>sin()</function> function and I get an error like this. -What does it mean? -<informalexample> -<screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment</screen> -</informalexample> -</para> - -<para>A. When using mathematical functions like -<function>sin()</function>, you have to tell <command>cc</command> to -link in the math library, like so: -<informalexample> -<screen>$ <userinput>cc -o foobar foobar.c -lm</userinput></screen> -</informalexample></para> - -<para>Q. All right, I wrote this simple program to practice using -<option>-lm</option>. All it does is raise 2.1 to the power of 6. -<informalexample> -<programlisting>#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -}</programlisting> -</informalexample> -and I compiled it as: -<informalexample> -<screen>$ <userinput>cc temp.c -lm</userinput></screen> -</informalexample> -like you said I should, but I get this when I run it: -<informalexample> -<screen>$ <userinput>./a.out</userinput> -2.1 ^ 6 = 1023.000000</screen> -</informalexample> -</para> - -<para>This is <emphasis>not</emphasis> the right answer! What is -going on?</para> - -<para>A. When the compiler sees you call a function, it checks if it -has already seen a prototype for it. If it has not, it assumes the -function returns an <type>int</type>, which is -definitely not what you want here.</para> - -<para>Q. So how do I fix this?</para> - -<para>A. The prototypes for the mathematical functions are in -<filename>math.h</filename>. If you include this file, the compiler -will be able to find the prototype and it will stop doing strange -things to your calculation! -<informalexample> -<programlisting>#include <math.h> -#include <stdio.h> - -int main() { -...</programlisting> -</informalexample> -</para> - -<para>After recompiling it as you did before, run it: -<informalexample> -<screen>$ <userinput>./a.out</userinput> -2.1 ^ 6 = 85.766121</screen> -</informalexample> -</para> - -<para>If you are using any of the mathematical functions, -<emphasis>always</emphasis> include <filename>math.h</filename> and -remember to link in the math library.</para> - -<para>Q. I compiled a file called <filename>foobar.c</filename> and I -cannot find an executable called <filename>foobar</filename>. Where's -it gone?</para> - -<para>A. Remember, <command>cc</command> will call the executable -<filename>a.out</filename> unless you tell it differently. Use the -<option>-o <replaceable>filename</replaceable></option> option: -<informalexample> -<screen>$ <userinput>cc -o foobar foobar.c</userinput></screen> -</informalexample> -</para> - -<para>Q. OK, I have an executable called <filename>foobar</filename>, -I can see it when I run <command>ls</command>, but when I type in -<command>foobar</command> at the command prompt it tells me there is -no such file. Why can it not find it?</para> - -<para>A. Unlike <trademark>MS-DOS</trademark>, Unix does not look in the -current directory when it is trying to find out which executable you -want it to run, unless you tell it to. Either type -<command>./foobar</command>, which means <quote>run the file called -<filename>foobar</filename> in the current directory</quote>, or -change your <systemitem class=environvar>PATH</systemitem> -environment variable so that it looks something like -<informalexample> -<screen>bin:/usr/bin:/usr/local/bin:.</screen> -</informalexample> -The dot at the end means <quote>look in the current directory if it is not in -any of the others</quote>.</para> - -<para>Q. I called my executable <filename>test</filename>, but -nothing happens when I run it. What is going on?</para> - -<para>A. Most Unix systems have a program called -<command>test</command> in <filename>/usr/bin</filename> and the -shell is picking that one up before it gets to checking the current -directory. Either type: -<informalexample> -<screen>$ <userinput>./test</userinput></screen> -</informalexample> -or choose a better name for your program!</para> - -<para>Q. I compiled my program and it seemed to run all right at -first, then there was an error and it said something about <errorname>core -dumped</errorname>. What does that mean?</para> - -<para>A. The name <firstterm>core dump</firstterm> dates back to the -very early days of Unix, when the machines used core memory for -storing data. Basically, if the program failed under certain -conditions, the system would write the contents of core memory to -disk in a file called <filename>core</filename>, which the programmer -could then pore over to find out what went wrong.</para> - -<para>Q. Fascinating stuff, but what I am supposed to do now?</para> - -<para>A. Use <command>gdb</command> to analyse the core (see <xref -linkend="debugging">).</para> - -<para>Q. When my program dumped core, it said something about a -<errorname>segmentation fault</errorname>. What's that?</para> - -<para>A. This basically means that your program tried to perform some sort -of illegal operation on memory; Unix is designed to protect the -operating system and other programs from rogue programs.</para> - -<para>Common causes for this are: -<itemizedlist> -<listitem><para>Trying to write to a <symbol>NULL</symbol> pointer, eg -<programlisting>char *foo = NULL; -strcpy(foo, "bang!");</programlisting> -</para></listitem> - -<listitem><para>Using a pointer that hasn't been initialised, eg -<programlisting>char *foo; -strcpy(foo, "bang!");</programlisting> -The pointer will have some random value that, with luck, -will point into an area of memory that isn't available to -your program and the kernel will kill your program before -it can do any damage. If you're unlucky, it'll point -somewhere inside your own program and corrupt one of your -data structures, causing the program to fail -mysteriously.</para></listitem> - -<listitem><para>Trying to access past the end of an array, eg -<programlisting>int bar[20]; -bar[27] = 6;</programlisting></para></listitem> - -<listitem><para> Trying to store something in read-only memory, eg -<programlisting>char *foo = "My string"; -strcpy(foo, "bang!");</programlisting> -Unix compilers often put string literals like -<literal>"My string"</literal> into -read-only areas of memory.</para></listitem> - -<listitem><para>Doing naughty things with -<function>malloc()</function> and <function>free()</function>, eg -<programlisting>char bar[80]; -free(bar);</programlisting> -or -<programlisting>char *foo = malloc(27); -free(foo); -free(foo);</programlisting> -</para></listitem> - -</itemizedlist></para> - -<para>Making one of these mistakes will not always lead to an -error, but they are always bad practice. Some systems and -compilers are more tolerant than others, which is why programs -that ran well on one system can crash when you try them on an -another.</para> - -<para>Q. Sometimes when I get a core dump it says <errorname>bus -error</errorname>. It says in my Unix book that this means a hardware -problem, but the computer still seems to be working. Is this -true?</para> - -<para>A. No, fortunately not (unless of course you really do have a hardware -problem…). This is usually another way of saying that you -accessed memory in a way you shouldn't have.</para> - -<para>Q. This dumping core business sounds as though it could be quite -useful, if I can make it happen when I want to. Can I do this, or -do I have to wait until there's an error?</para> - -<para>A. Yes, just go to another console or xterm, do -<screen>$ <userinput>ps</userinput></screen> -to find out the process ID of your program, and do -<screen>$ <userinput>kill -ABRT <replaceable>pid</replaceable></userinput></screen> -where <parameter><replaceable>pid</replaceable></parameter> is the -process ID you looked up.</para> - -<para>This is useful if your program has got stuck in an infinite -loop, for instance. If your program happens to trap -<symbol>SIGABRT</symbol>, there are several other signals which have -a similar effect.</para> - -</sect1> -</chapter> - - -<chapter> -<title>Make</title> - -<sect1> -<title>What is <command>make</command>?</title> - -<para>When you're working on a simple program with only one or two source -files, typing in -<screen>$ <userinput>cc file1.c file2.c</userinput></screen> -is not too bad, but it quickly becomes very tedious when there are -several files—and it can take a while to compile, too.</para> - -<para>One way to get around this is to use object files and only recompile -the source file if the source code has changed. So we could have -something like: -<screen>$ <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> &hellip</screen> -if we'd changed <filename>file37.c</filename>, but not any of the -others, since the last time we compiled. This may speed up the -compilation quite a bit, but doesn't solve the typing -problem.</para> - -<para>Or we could write a shell script to solve the typing problem, but it -would have to re-compile everything, making it very inefficient on a -large project.</para> - -<para>What happens if we have hundreds of source files lying about? What if -we're working in a team with other people who forget to tell us when -they've changed one of their source files that we use?</para> - -<para>Perhaps we could put the two solutions together and write something -like a shell script that would contain some kind of magic rule saying -when a source file needs compiling. Now all we need now is a program -that can understand these rules, as it's a bit too complicated for the -shell.</para> - -<para>This program is called <command>make</command>. It reads in a -file, called a <firstterm>makefile</firstterm>, that tells it how -different files depend on each other, and works out which files need -to be re-compiled and which ones don't. For example, a rule could say -something like <quote>if <filename>fromboz.o</filename> is older than -<filename>fromboz.c</filename>, that means someone must have changed -<filename>fromboz.c</filename>, so it needs to be -re-compiled.</quote> The makefile also has rules telling make -<emphasis>how</emphasis> to re-compile the source file, making it a -much more powerful tool.</para> - -<para>Makefiles are typically kept in the same directory as the -source they apply to, and can be called -<filename>makefile</filename>, <filename>Makefile</filename> or -<filename>MAKEFILE</filename>. Most programmers use the name -<filename>Makefile</filename>, as this puts it near the top of a -directory listing, where it can easily be seen.<footnote><para>They -don't use the <filename>MAKEFILE</filename> form as block capitals -are often used for documentation files like -<filename>README</filename>.</para></footnote></para> - -</sect1> - -<sect1> -<title>Example of using <command>make</command></title> - -<para>Here's a very simple make file: -<programlisting>foo: foo.c - cc -o foo foo.c</programlisting> -It consists of two lines, a dependency line and a creation line.</para> - -<para>The dependency line here consists of the name of the program -(known as the <firstterm>target</firstterm>), followed by a colon, -then whitespace, then the name of the source file. When -<command>make</command> reads this line, it looks to see if -<filename>foo</filename> exists; if it exists, it compares the time -<filename>foo</filename> was last modified to the time -<filename>foo.c</filename> was last modified. If -<filename>foo</filename> does not exist, or is older than -<filename>foo.c</filename>, it then looks at the creation line to -find out what to do. In other words, this is the rule for working out -when <filename>foo.c</filename> needs to be re-compiled.</para> - -<para>The creation line starts with a <token>tab</token> (press the -<keycap>tab</keycap> key) and then the command you would type to -create <filename>foo</filename> if you were doing it at a command -prompt. If <filename>foo</filename> is out of date, or does not -exist, <command>make</command> then executes this command to create -it. In other words, this is the rule which tells make how to -re-compile <filename>foo.c</filename>.</para> - -<para>So, when you type <userinput>make</userinput>, it will make -sure that <filename>foo</filename> is up to date with respect to your -latest changes to <filename>foo.c</filename>. This principle can be -extended to <filename>Makefile</filename>s with hundreds of -targets—in fact, on FreeBSD, it is possible to compile the -entire operating system just by typing <userinput>make -world</userinput> in the appropriate directory!</para> - -<para>Another useful property of makefiles is that the targets don't have -to be programs. For instance, we could have a make file that looks -like this: -<programlisting>foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me</programlisting></para> - -<para>We can tell make which target we want to make by typing: -<screen>$ <userinput>make <replaceable>target</replaceable></userinput></screen> -<command>make</command> will then only look at that target and ignore any -others. For example, if we type <userinput>make foo</userinput> with the -makefile above, make will ignore the <action>install</action> target.</para> - -<para>If we just type <userinput>make</userinput> on its own, make -will always look at the first target and then stop without looking at -any others. So if we typed <userinput>make</userinput> here, it will -just go to the <action>foo</action> target, re-compile -<filename>foo</filename> if necessary, and then stop without going on -to the <action>install</action> target.</para> - -<para>Notice that the <action>install</action> target doesn't -actually depend on anything! This means that the command on the -following line is always executed when we try to make that target by -typing <userinput>make install</userinput>. In this case, it will -copy <filename>foo</filename> into the user's home directory. This is -often used by application makefiles, so that the application can be -installed in the correct directory when it has been correctly -compiled.</para> - -<para>This is a slightly confusing subject to try and explain. If you -don't quite understand how <command>make</command> works, the best -thing to do is to write a simple program like <quote>hello -world</quote> and a make file like the one above and experiment. Then -progress to using more than one source file, or having the source -file include a header file. The <command>touch</command> command is -very useful here—it changes the date on a file without you -having to edit it.</para> - -</sect1> - -<sect1> -<title>FreeBSD Makefiles</title> - -<para>Makefiles can be rather complicated to write. Fortunately, -BSD-based systems like FreeBSD come with some very powerful ones as -part of the system. One very good example of this is the FreeBSD -ports system. Here's the essential part of a typical ports -<filename>Makefile</filename>: -<programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk></programlisting></para> - -<para>Now, if we go to the directory for this port and type -<userinput>make</userinput>, the following happens:</para> - -<procedure> -<step><para>A check is made to see if the source code for this port is -already on the system.</para></step> - -<step><para>If it isn't, an FTP connection to the URL in -<symbol>MASTER_SITES</symbol> is set up to download the -source.</para></step> - -<step><para>The checksum for the source is calculated and compared it with -one for a known, good, copy of the source. This is to make sure that -the source was not corrupted while in transit.</para></step> - -<step><para>Any changes required to make the source work on FreeBSD are -applied—this is known as <firstterm>patching</firstterm>.</para></step> - -<step><para>Any special configuration needed for the source is done. -(Many Unix program distributions try to work out which version of -Unix they are being compiled on and which optional Unix features are -present—this is where they are given the information in the -FreeBSD ports scenario).</para></step> - -<step><para>The source code for the program is compiled. In effect, -we change to the directory where the source was unpacked and do -<command>make</command>—the program's own make file has the -necessary information to build the program.</para></step> - -<step><para>We now have a compiled version of the program. If we -wish, we can test it now; when we feel confident about the program, -we can type <userinput>make install</userinput>. This will cause the -program and any supporting files it needs to be copied into the -correct location; an entry is also made into a <database>package -database</database>, so that the port can easily be uninstalled later -if we change our mind about it.</para></step> - -</procedure> - -<para>Now I think you'll agree that's rather impressive for a four -line script!</para> - -<para>The secret lies in the last line, which tells -<command>make</command> to look in the system makefile called -<filename>bsd.port.mk</filename>. It's easy to overlook this line, -but this is where all the clever stuff comes from—someone has -written a makefile that tells <command>make</command> to do all the -things above (plus a couple of other things I didn't mention, -including handling any errors that may occur) and anyone can get -access to that just by putting a single line in their own make -file!</para> - -<para>If you want to have a look at these system makefiles, they're -in <filename>/usr/share/mk</filename>, but it's probably best to wait -until you've had a bit of practice with makefiles, as they are very -complicated (and if you do look at them, make sure you have a flask -of strong coffee handy!)</para> - -</sect1> - -<sect1> -<title>More advanced uses of <command>make</command></title> - -<para><command>Make</command> is a very powerful tool, and can do much -more than the simple example above shows. Unfortunately, there are -several different versions of <command>make</command>, and they all -differ considerably. The best way to learn what they can do is -probably to read the documentation—hopefully this introduction will -have given you a base from which you can do this.</para> - -<para>The version of make that comes with FreeBSD is the <application>Berkeley -make</application>; there is a tutorial for it in -<filename>/usr/share/doc/psd/12.make</filename>. To view it, do -<screen>$ <userinput>zmore paper.ascii.gz</userinput></screen> -in that directory.</para> - -<para>Many applications in the ports use <application>GNU -make</application>, which has a very good set of <quote>info</quote> -pages. If you have installed any of these ports, <application>GNU -make</application> will automatically have been installed as -<command>gmake</command>. It's also available as a port and package -in its own right.</para> - -<para>To view the info pages for <application>GNU make</application>, -you will have to edit the <filename>dir</filename> file in the -<filename>/usr/local/info</filename> directory to add an entry for -it. This involves adding a line like -<programlisting> * Make: (make). The GNU Make utility.</programlisting> -to the file. Once you have done this, you can type -<userinput>info</userinput> and then select -<guimenuitem>make</guimenuitem> from the menu (or in -<application>Emacs</application>, do <userinput>C-h -i</userinput>).</para> - -</sect1> -</chapter> - -<chapter id="debugging"> -<title>Debugging</title> - -<sect1> -<title>The Debugger</title> - -<para>The debugger that comes with FreeBSD is called -<command>gdb</command> (<application>GNU -debugger</application>). You start it up by typing -<screen>$ <userinput>gdb <replaceable>progname</replaceable></userinput></screen> -although most people prefer to run it inside -<application>Emacs</application>. You can do this by: -<screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput></screen></para> - -<para>Using a debugger allows you to run the program under more -controlled circumstances. Typically, you can step through the program -a line at a time, inspect the value of variables, change them, tell -the debugger to run up to a certain point and then stop, and so on. -You can even attach to a program that's already running, or load a -core file to investigate why the program crashed. It's even possible -to debug the kernel, though that's a little trickier than the user -applications we'll be discussing in this section.</para> - -<para><command>gdb</command> has quite good on-line help, as well as -a set of info pages, so this section will concentrate on a few of the -basic commands.</para> - -<para>Finally, if you find its text-based command-prompt style -off-putting, there's a graphical front-end for it <ulink -URL="../../ports/devel.html">xxgdb</ulink> -in the ports collection.</para> - -<para>This section is intended to be an introduction to using -<command>gdb</command> and does not cover specialised topics such as -debugging the kernel.</para> - -</sect1> - -<sect1> -<title>Running a program in the debugger</title> - -<para>You'll need to have compiled the program with the -<option>-g</option> option to get the most out of using -<command>gdb</command>. It will work without, but you'll only see the -name of the function you're in, instead of the source code. If you -see a line like: -<screen>… (no debugging symbols found) …</screen>when -<command>gdb</command> starts up, you'll know that the program wasn't -compiled with the <option>-g</option> option.</para> - -<para>At the <command>gdb</command> prompt, type <userinput>break -main</userinput>. This will tell the debugger to skip over the -preliminary set-up code in the program and start at the beginning of -your code. Now type <userinput>run</userinput> to start the -program—it will start at the beginning of the set-up code and -then get stopped by the debugger when it calls -<function>main()</function>. (If you've ever wondered where -<function>main()</function> gets called from, now you know!).</para> - -<para>You can now step through the program, a line at a time, by -pressing <command>n</command>. If you get to a function call, you can -step into it by pressing <command>s</command>. Once you're in a -function call, you can return from stepping into a function call by -pressing <command>f</command>. You can also use <command>up</command> and -<command>down</command> to take a quick look at the caller.</para> - -<para>Here's a simple example of how to spot a mistake in a program -with <command>gdb</command>. This is our program (with a deliberate -mistake): -<programlisting>#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -}</programlisting> -</para> - -<para>This program sets <symbol>i</symbol> to be <literal>5</literal> -and passes it to a function <function>bazz()</function> which prints -out the number we gave it.</para> - -<para>When we compile and run the program we get -<screen>$ <userinput>cc -g -o temp temp.c</userinput> -$ <userinput>./temp</userinput> -This is my program -anint = 4231</screen></para> - -<para>That wasn't what we expected! Time to see what's going -on!<screen>$ <userinput>gdb temp</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.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>break main</> <lineannotation>Skip the set-up code</> -Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation><command>gdb</command> puts breakpoint at <function>main()</></> -(gdb) <userinput>run</> <lineannotation>Run as far as <function>main()</></> -Starting program: /home/james/tmp/temp <lineannotation>Program starts running</> - -Breakpoint 1, main () at temp.c:9 <lineannotation><command>gdb</command> stops at <function>main()</></> -(gdb) <userinput>n</> <lineannotation>Go to next line</> -This is my program <lineannotation>Program prints out</> -(gdb) <userinput>s</> <lineannotation>step into <function>bazz()</></> -bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays stack frame</> -(gdb)</screen></para> - - -<para>Hang on a minute! How did <symbol>anint</symbol> get to be -<literal>4231</literal>? Didn't we set it to be <literal>5</literal> -in <function>main()</function>? Let's move up to -<function>main()</function> and have a look.</para> - -<para><screen>(gdb) <userinput>up</> <lineannotation>Move up call stack</> -#1 0x1625 in main () at temp.c:11 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) <userinput>p i</> <lineannotation>Show us the value of <symbol>i</></> -$1 = 4231 <lineannotation><command>gdb</command> displays <literal>4231</></></screen> -Oh dear! Looking at the code, we forgot to initialise -<symbol>i</symbol>. We meant to put -<programlisting><lineannotation>…</> -main() { - int i; - - i = 5; - printf("This is my program\n"); -<lineannotation>&hellip</></programlisting> -but we left the <literal>i=5;</literal> line out. As we didn't -initialise <symbol>i</symbol>, it had whatever number happened to be -in that area of memory when the program ran, which in this case -happened to be <literal>4231</literal>.</para> - -<note><para><command>gdb</command> displays the stack frame -every time we go into or out of a function, even if we're using -<command>up</command> and <command>down</command> to move around the -call stack. This shows the name of the function and the values of -its arguments, which helps us keep track of where we are and what's -going on. (The stack is a storage area where the program stores -information about the arguments passed to functions and where to go -when it returns from a function call).</para></note> - -</sect1> - -<sect1> -<title>Examining a core file</title> - -<para>A core file is basically a file which contains the complete -state of the process when it crashed. In <quote>the good old -days</quote>, programmers had to print out hex listings of core files -and sweat over machine code manuals, but now life is a bit easier. -Incidentally, under FreeBSD and other 4.4BSD systems, a core file is -called <filename><replaceable>progname</>.core</> instead of just -<filename>core</filename>, to make it clearer which program a core -file belongs to.</para> - -<para>To examine a core file, start up <command>gdb</command> in the -usual way. Instead of typing <command>break</command> or -<command>run</command>, type -<screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput></screen> -If you're not in the same directory as the core file, you'll have to -do <userinput>dir /path/to/core/file</userinput> first.</para> - -<para>You should see something like this: -<screen>$ <userinput>gdb a.out</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.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>core a.out.core</userinput> -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb)</screen></para> - -<para>In this case, the program was called -<filename>a.out</filename>, so the core file is called -<filename>a.out.core</filename>. We can see that the program crashed -due to trying to access an area in memory that was not available to -it in a function called <function>bazz</function>.</para> - -<para>Sometimes it's useful to be able to see how a function was -called, as the problem could have occurred a long way up the call -stack in a complex program. The <command>bt</command> command causes -<command>gdb</command> to print out a back-trace of the call -stack: -<screen>(gdb) <userinput>bt</userinput> -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb)</screen>The <function>end()</function> function is called when -a program crashes; in this case, the <function>bazz()</function> -function was called from <function>main()</function>.</para> - -</sect1> - -<sect1> -<title>Attaching to a running program</title> - -<para>One of the neatest features about <command>gdb</command> is -that it can attach to a program that's already running. Of course, -that assumes you have sufficient permissions to do so. A common -problem is when you are stepping through a program that forks, and -you want to trace the child, but the debugger will only let you trace -the parent.</para> - -<para>What you do is start up another <command>gdb</command>, use -<command>ps</command> to find the process ID for the child, and -do<screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput></screen> -in <command>gdb</command>, and then debug as usual.</para> - -<para><quote>That's all very well,</quote> you're probably thinking, -<quote>but by the time I've done that, the child process will be over -the hill and far away</quote>. Fear not, gentle reader, here's how to -do it (courtesy of the <command>gdb</command> info pages): -<screen><lineannotation>&hellip</lineannotation> -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - <lineannotation>&hellip</lineannotation> -} else { /* parent */ - <lineannotation>&hellip</lineannotation></screen> -Now all you have to do is attach to the child, set -<symbol>PauseMode</symbol> to <literal>0</literal>, and -wait for the <function>sleep()</function> call to return!</para> - -</sect1> -</chapter> - -<chapter id="emacs"> -<title>Using Emacs as a Development Environment</title> - -<sect1> -<title>Emacs</title> - -<para>Unfortunately, Unix systems don't come with the kind of -everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package -integrated development environments that other systems -have.<footnote><para>At least, not unless you pay out very large sums -of money.</para></footnote> However, it is possible to set up your -own environment. It may not be as pretty, and it may not be quite as -integrated, but you can set it up the way you want it. And it's free. -And you have the source to it.</para> - -<para>The key to it all is Emacs. Now there are some people who -loathe it, but many who love it. If you're one of the former, I'm -afraid this section will hold little of interest to you. Also, you'll -need a fair amount of memory to run it—I'd recommend 8MB in -text mode and 16MB in X as the bare minimum to get reasonable -performance.</para> - -<para>Emacs is basically a highly customisable editor—indeed, -it has been customised to the point where it's more like an operating -system than an editor! Many developers and sysadmins do in fact -spend practically all their time working inside Emacs, leaving it -only to log out.</para> - -<para>It's impossible even to summarise everything Emacs can do here, but -here are some of the features of interest to developers: -<itemizedlist> - -<listitem><para>Very powerful editor, allowing search-and-replace on -both strings and regular expressions (patterns), jumping to start/end -of block expression, etc, etc.</para></listitem> - -<listitem><para>Pull-down menus and online help.</para></listitem> - -<listitem><para>Language-dependent syntax highlighting and -indentation.</para></listitem> - -<listitem><para>Completely customisable.</para></listitem> - -<listitem><para>You can compile and debug programs within -Emacs.</para></listitem> - -<listitem><para>On a compilation error, you can jump to the offending -line of source code.</para></listitem> - -<listitem><para>Friendly-ish front-end to the <command>info</command> -program used for reading GNU hypertext documentation, including the -documentation on Emacs itself.</para></listitem> - -<listitem><para>Friendly front-end to <command>gdb</command>, -allowing you to look at the source code as you step through your -program.</para></listitem> - -<listitem><para>You can read Usenet news and mail while your program -is compiling.</para></listitem> - -</itemizedlist>And doubtless many more that I've overlooked.</para> - -<para>Emacs can be installed on FreeBSD using <ulink -URL="../../ports/editors.html">the Emacs -port</ulink>.</para> - -<para>Once it's installed, start it up and do <userinput>C-h -t</userinput> to read an Emacs tutorial—that means hold down -the <keycap>control</keycap> key, press <keycap>h</keycap>, let go of -the <keycap>control</keycap> key, and then press <keycap>t</keycap>. -(Alternatively, you can you use the mouse to select <guimenuitem>Emacs -Tutorial</guimenuitem> from the <guimenu>Help</guimenu> menu).</para> - -<para>Although Emacs does have menus, it's well worth learning the -key bindings, as it's much quicker when you're editing something to -press a couple of keys than to try and find the mouse and then click -on the right place. And, when you're talking to seasoned Emacs users, -you'll find they often casually throw around expressions like -<quote><literal>M-x replace-s RET foo RET bar RET</literal></quote> -so it's useful to know what they mean. And in any case, Emacs has far -too many useful functions for them to all fit on the menu -bars.</para> - -<para>Fortunately, it's quite easy to pick up the key-bindings, as -they're displayed next to the menu item. My advice is to use the -menu item for, say, opening a file until you understand how it works -and feel confident with it, then try doing C-x C-f. When you're happy -with that, move on to another menu command.</para> - -<para>If you can't remember what a particular combination of keys -does, select <guimenuitem>Describe Key</guimenuitem> from the -<guimenu>Help</guimenu> menu and type it in—Emacs will tell you -what it does. You can also use the <guimenuitem>Command -Apropos</guimenuitem> menu item to find out all the commands which -contain a particular word in them, with the key binding next to -it.</para> - -<para>By the way, the expression above means hold down the -<keysym>Meta</keysym> key, press <keysym>x</keysym>, release the -<keysym>Meta</keysym> key, type <userinput>replace-s</userinput> -(short for <literal>replace-string</literal>—another feature of -Emacs is that you can abbreviate commands), press the -<keysym>return</keysym> key, type <userinput>foo</userinput> (the -string you want replaced), press the <keysym>return</keysym> key, -type bar (the string you want to replace <literal>foo</literal> with) -and press <keysym>return</keysym> again. Emacs will then do the -search-and-replace operation you've just requested.</para> - -<para>If you're wondering what on earth the <keysym>Meta</keysym> key -is, it's a special key that many Unix workstations have. -Unfortunately, PC's don't have one, so it's usually the -<keycap>alt</keycap> key (or if you're unlucky, the <keysym>escape</keysym> -key).</para> - -<para>Oh, and to get out of Emacs, do <command>C-x C-c</command> -(that means hold down the <keysym>control</keysym> key, press -<keysym>x</keysym>, press <keysym>c</keysym> and release the -<keysym>control</keysym> key). If you have any unsaved files open, -Emacs will ask you if you want to save them. (Ignore the bit in the -documentation where it says <command>C-z</command> is the usual way -to leave Emacs—that leaves Emacs hanging around in the -background, and is only really useful if you're on a system which -doesn't have virtual terminals).</para> - -</sect1> - -<sect1> -<title>Configuring Emacs</title> - -<para>Emacs does many wonderful things; some of them are built in, -some of them need to be configured.</para> - -<para>Instead of using a proprietary macro language for -configuration, Emacs uses a version of Lisp specially adapted for -editors, known as Emacs Lisp. This can be quite useful if you want to -go on and learn something like Common Lisp, as it's considerably -smaller than Common Lisp (although still quite big!).</para> - -<para>The best way to learn Emacs Lisp is to download the <ulink -URL="ftp://prep.ai.mit.edu:pub/gnu/elisp-manual-19-2.4.tar.gz">Emacs -Tutorial</ulink></para> - -<para>However, there's no need to actually know any Lisp to get -started with configuring Emacs, as I've included a sample -<filename>.emacs</filename> file, which should be enough to get you -started. Just copy it into your home directory and restart Emacs if -it's already running; it will read the commands from the file and -(hopefully) give you a useful basic setup.</para> - -</sect1> - -<sect1> -<title>A sample <filename>.emacs</filename> file</title> - -<para>Unfortunately, there's far too much here to explain it in detail; -however there are one or two points worth mentioning.</para> - -<para> -<itemizedlist> - -<listitem><para>Everything beginning with a <literal>;</> is a -comment and is ignored by Emacs.</para></listitem> - -<listitem><para>In the first line, the -<literal>-*- Emacs-Lisp -*-</literal> is so that we can -edit the <filename>.emacs</filename> file itself within Emacs and get -all the fancy features for editing Emacs Lisp. Emacs usually tries to -guess this based on the filename, and may not get it right for -<filename>.emacs</filename>. </para></listitem> - -<listitem><para>The <keysym>tab</keysym> key is bound to an -indentation function in some modes, so when you press the tab key, it -will indent the current line of code. If you want to put a -<token>tab</token> character in whatever you're writing, hold the -<keysym>control</keysym> key down while you're pressing the -<keysym>tab</keysym> key.</para></listitem> - -<listitem><para>This file supports syntax highlighting for C, C++, -Perl, Lisp and Scheme, by guessing the language from the -filename.</para></listitem> - -<listitem><para>Emacs already has a pre-defined function called -<function>next-error</function>. In a compilation output window, this -allows you to move from one compilation error to the next by doing -<command>M-n</command>; we define a complementary function, -<function>previous-error</function>, that allows you to go to a -previous error by doing <command>M-p</command>. The nicest feature of -all is that <command>C-c C-c</command> will open up the source file -in which the error occurred and jump to the appropriate -line.</para></listitem> - -<listitem><para> We enable Emacs's ability to act as a server, so -that if you're doing something outside Emacs and you want to edit a -file, you can just type in -<screen>$ <userinput>emacsclient <replaceable>filename</replaceable></userinput></screen> -and then you can edit the file in your Emacs!<footnote><para>Many -Emacs users set their <systemitem -class=environvar>EDITOR</systemitem> environment to -<literal>emacsclient</literal> so this happens every time they need -to edit a file.</para></footnote></para></listitem> - -</itemizedlist> -</para> - -<example> -<title>A sample <filename>.emacs</filename> file</title> -<screen>;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") </screen> - -<screen>(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n)))</screen> - -<screen>;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") -</screen> -</example> - -</sect1> - -<sect1> -<title>Extending the Range of Languages Emacs Understands</title> - -<para>Now, this is all very well if you only want to program in the -languages already catered for in the <filename>.emacs</filename> file -(C, C++, Perl, Lisp and Scheme), but what happens if a new language -called <quote>whizbang</quote> comes out, full of exciting -features?</para> - -<para>The first thing to do is find out if whizbang -comes with any files that tell Emacs about the language. These -usually end in <filename>.el</filename>, short for <quote>Emacs -Lisp</quote>. For example, if whizbang is a FreeBSD -port, we can locate these files by doing -<screen>$ <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput></screen> -and install them by copying them into the Emacs site Lisp directory. On -FreeBSD 2.1.0-RELEASE, this is -<filename>/usr/local/share/emacs/site-lisp</filename>.</para> - -<para>So for example, if the output from the find command was -<screen>/usr/ports/lang/whizbang/work/misc/whizbang.el</screen> -we would do -<screen>$ <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput></screen> -</para> - -<para>Next, we need to decide what extension whizbang source files -have. Let's say for the sake of argument that they all end in -<filename>.wiz</filename>. We need to add an entry to our -<filename>.emacs</filename> file to make sure Emacs will be able to -use the information in <filename>whizbang.el</filename>.</para> - -<para>Find the <symbol>auto-mode-alist entry</symbol> in -<filename>.emacs</filename> and add a line for whizbang, such -as: -<programlisting><lineannotation>…</> -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -<lineannotation>…</></programlisting> -This means that Emacs will automatically go into -<function>whizbang-mode</function> when you edit a file ending in -<filename>.wiz</filename>.</para> - -<para>Just below this, you'll find the -<symbol>font-lock-auto-mode-list</symbol> entry. Add -<function>whizbang-mode</function> to it like so: -<programlisting>;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode")</programlisting> -This means that Emacs will always enable -<function>font-lock-mode</function> (ie syntax highlighting) when -editing a <filename>.wiz</filename> file.</para> - -<para>And that's all that's needed. If there's anything else you want -done automatically when you open up a <filename>.wiz</filename> file, -you can add a <function>whizbang-mode hook</function> (see -<function>my-scheme-mode-hook</function> for a simple example that -adds <function>auto-indent</function>).</para> - -</sect1> -</chapter> - -<chapter> -<title>Further Reading</title> - -<itemizedlist> -<listitem><para>Brian Harvey and Matthew Wright -<emphasis>Simply Scheme</emphasis> -MIT 1994.<!-- <br> --> -ISBN 0-262-08226-8</para></listitem> - -<listitem><para>Randall Schwartz -<emphasis>Learning Perl</emphasis> -O'Reilly 1993<!-- <br> --> -ISBN 1-56592-042-2</para></listitem> - -<listitem><para>Patrick Henry Winston and Berthold Klaus Paul Horn -<emphasis>Lisp (3rd Edition)</emphasis> -Addison-Wesley 1989<!-- <br> --> -ISBN 0-201-08319-1</para></listitem> - -<listitem><para>Brian W. Kernighan and Rob Pike -<emphasis>The Unix Programming Environment</emphasis> -Prentice-Hall 1984<!-- <br> --> -ISBN 0-13-937681-X</para></listitem> - -<listitem><para>Brian W. Kernighan and Dennis M. Ritchie -<emphasis>The C Programming Language (2nd Edition)</emphasis> -Prentice-Hall 1988<!-- <br> --> -ISBN 0-13-110362-8</para></listitem> - -<listitem><para>Bjarne Stroustrup -<emphasis>The C++ Programming Language</emphasis> -Addison-Wesley 1991<!-- <br> --> -ISBN 0-201-53992-6</para></listitem> - -<listitem><para>W. Richard Stevens -<emphasis>Advanced Programming in the Unix Environment</emphasis> -Addison-Wesley 1992<!-- <br> --> -ISBN 0-201-56317-7</para></listitem> - -<listitem><para>W. Richard Stevens -<emphasis>Unix Network Programming</emphasis> -Prentice-Hall 1990<!-- <br> --> -ISBN 0-13-949876-1</para></listitem> - -</itemizedlist> - -</chapter> -</book> diff --git a/en/tutorials/diskformat/Makefile b/en/tutorials/diskformat/Makefile deleted file mode 100644 index 158bc4d801..0000000000 --- a/en/tutorials/diskformat/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.1 1997-09-13 04:24:23 jfieber Exp $ - -DOCS= diskformat.docb -INDEXLINK= diskformat.html - -.include "../../web.mk" - diff --git a/en/tutorials/diskformat/diskformat.docb b/en/tutorials/diskformat/diskformat.docb deleted file mode 100644 index d591b9f207..0000000000 --- a/en/tutorials/diskformat/diskformat.docb +++ /dev/null @@ -1,464 +0,0 @@ -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<!-- $Id: diskformat.docb,v 1.5 1998-10-14 03:25:31 dwhite Exp $ --> -<book> - -<bookinfo> -<bookbiblio> -<title>Formatting Media For Use With FreeBSD 2.2-RELEASE</title> -<subtitle>A Tutorial</subtitle> - -<authorgroup> -<author> -<firstname>Doug</firstname> -<surname>White</surname> -<affiliation> -<address><email>dwhite@resnet.uoregon.edu</email></address> -</affiliation> -</author> -</authorgroup> - -<pubdate>March 1997</pubdate> -<abstract><para>This document describes how to slice, partition, and -format hard disk drives and similar media for use with FreeBSD. The -examples given have been tested under FreeBSD 2.2-GAMMA and may work -for other releases. </para> -</abstract> -</bookbiblio> -</bookinfo> - -<chapter> -<title>Introduction & Definitions</title> - -<sect1> -<title>Overview</title> -<para>Successfully adding disks to an existing system is the mark of an -experienced system administrator. Slicing, partitioning, and adding -disks requires a careful dance of proper command and name syntax. One -slipped finger and an entire disk could disappear in seconds. This -document is written in an attempt to simplify this process and avoid -accidents. Thankfully, enhancements to existing tools (notably -sysinstall) have greatly improved this process in recent releases of -FreeBSD. </para> - -<para>There are two possible modes of disk formatting: -<itemizedlist> - -<listitem><para><firstterm>compatibility mode</firstterm>: Arranging a -disk so that it has a slice table for use with other operating -systems.</para> </listitem> - -<listitem><para><firstterm>dangerously dedicated mode</firstterm>: -Formatting a disk with no slice table. This makes the process of -adding disks easier, however non-FreeBSD operating systems may not -accept the disk. </para> </listitem> -</itemizedlist> -</para> - -<para>For most cases, dedicated mode is the easiest to set up and use -in existing systems, as a new disk is usually dedicated entirely to -FreeBSD. However, compatibility mode insures optimum interoperability -with future installations at a cost of increased complexity.</para> - -<para>In addition to selecting the mode, two methods of slicing the -disk are available. One is using the system installation tool -<command>/stand/sysinstall</command>. 2.1.7-RELEASE and later -versions of <command>sysinstall</command> contain code to ease setup -of disks during normal system operation, mainly allowing access to the -Label and Partition editors and a Write feature which will update just -the selected disk and slice without affecting other disks. The other -method is running the tools manually from a root command line. For -dangerously dedicated mode, only three or four commands are involved -while <command>sysinstall</command> requires some manipulation.</para> -</sect1> -<sect1> -<title>Definitions</title> - -<para>UNIX disk management over the centuries has invented many new -definitions for old words. The following glossary covers the -definitions used in this document and (hopefully) for FreeBSD in -general. </para> - -<!-- I'm tempted to use GLOSSARY here but will resort to a list for -now. --> - -<itemizedlist> -<listitem><para>compatibility mode: Arranging a disk so that it has a slice -table for use with other operating systems. Oppose dangerously -dedicated mode.</para></listitem> - -<listitem><para>dangerously dedicated mode: Formatting a disk with no slice -table. This makes the process of adding disks easier, however -non-FreeBSD operating systems may not accept the disk. Oppose -compatibility mode.</para></listitem> - -<listitem><para>disk: A circular disc, covered with magnetic or similarly -manipulable material, spun by a motor under a head. Data is stored on -the disk by changing the pattern of magnetism on the disc, which can -be later read. Hard disks, CD-ROMs, Magneto-optical,and Zip/Jaz -removables are examples of disks.</para></listitem> - -<listitem><para>slice: A division of a disk. Up to four slices are permitted on one -disk in the PC standard. Slices are composed of contiguous sectors. -Slices are recorded in a <quote>slice table</quote> used by the system BIOS to -locate bootable partitions. The slice table is usually called the -Partition Table in DOS parlance. Maintained by the fdisk utility.</para></listitem> - -<listitem><para>partition: A division of a slice. Usually used in reference -to divisions of the FreeBSD slice of a disk. Each filesystem and swap -area on a disk resides in a partition. Maintained using the disklabel -utility.</para></listitem> - -<listitem><para>sector: Smallest subdivision of a disk. One sector usually -represents 512 bytes of data.</para></listitem> - -</itemizedlist> -</sect1> - -<sect1> -<title>Warnings & Pitfalls</title> - -<para>Building disks is not something to take lightly. It is quite possible -to destroy the contents of other disks in your system if the proper -precautions are not taken.</para> - -<para><emphasis>Check your work carefully.</> It is very simple to destroy -the incorrect disk when working with these commands. When -in doubt consult the kernel boot output for the proper device.</para> - -<para>Needless to say, we are not responsible for any damage to any data -or hardware that you may experience. You work at your own risk!</para> - -</sect1> - -<sect1> -<title>Zip, Jaz, and Other Removables</title> - -<para>Removable disks can be formatted in the same way as normal hard -disks. It is essential to have the disk drive connected to the system -and a disk placed in the drive during startup, so the kernel can -determine the drive's geometry. Check the <command>dmesg</command> -output and make sure your device and the disk's size is listed. If -the kernel reports -<informalexample> -<screen> -Can't get the size -</screen> -</informalexample> -then the disk was not in the drive. In this case, you will need to restart the -machine before attempting to format disks. -</para> -</sect1> - -</chapter> -<chapter> -<title>Formatting Disks in Dedicated Mode</title> - -<sect1> -<title>Introduction</title> - -<para>This section details how to make disks that are totally dedicated to -FreeBSD. Remember, dedicated mode disks cannot be booted by the PC -architecture.</para> - -</sect1> -<sect1> -<title>Making Dedicated Mode Disks using Sysinstall</title> - -<para><command>/stand/sysinstall</command>, the system installation -utility, has been expanded in recent versions to make the process of -dividing disks properly a less tiring affair. The fdisk and disklabel -editors built into sysinstall are GUI tools that remove much of the -confusion from slicing disks. For FreeBSD versions 2.1.7 and later, -this is perhaps the simplest way to slice disks.</para> - -<orderedlist> -<listitem><para>Start sysinstall as root by typing -<informalexample> -<screen><userinput>/stand/sysinstall</userinput></screen> -</informalexample> -from the command prompt.</para></listitem> - -<listitem><para>Select <command>Index</command>.</para></listitem> -<listitem><para>Select <command>Partition</command>.</para></listitem> -<listitem><para>Select the disk to edit with arrow keys and -<keycap>SPACE</keycap>.</para> -</listitem> -<listitem><para>If you are using this entire disk for FreeBSD, select -<command>A</command>.</para></listitem> -<listitem><para>When asked: -<informalexample> -<screen> -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? -</screen> -</informalexample>answer <command>No</command>.</para></listitem> -<listitem><para>When asked if you still want to do this, answer -<command>Yes</command>.</para></listitem> -<listitem><para>Select <command>Write</command>.</para></listitem> -<listitem><para>When warned about Writing on installed systems, answer -<command>Yes</command>.</para></listitem> -<listitem><para><command>Quit</command>the FDISK Editor and -<keycap>ESCAPE</keycap> back to the Index menu.</para></listitem> -<listitem><para>Select <command>Label</command> from the Index -menu.</para></listitem> -<listitem><para>Label as desired. For a single partition, enter -<command>C</command> to Create a partition, accept the -default size, partition type Filesystem, and a mountpoint (which isn't -used).</para></listitem> -<listitem><para>Enter <command>W</command> when done and confirm to -continue. The filesystem will be newfs'd for you, unless you select -otherwise (for news partitions you'll want to do this!). You'll get -the error: -<informalexample> -<screen>Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory </screen> -</informalexample> -Ignore. -</para></listitem> -<listitem><para>Exit out by repeatedly pressing <keycap>ESCAPE</keycap>.</para></listitem> -</orderedlist> - -</sect1> -<sect1> -<title>Making Dedicated Mode Disks Using the Command Line</title> - - -<para>Execute the following commands, replacing wd2 with the disk -name. Lines beginning with # are comments. </para> -<informalexample> -<screen> -<userinput> - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/rwd2 | disklabel -B -R -r wd2 /dev/stdin - # We only want one partition, so using slice 'c' should be fine: - newfs /dev/rwd2c -</userinput> -</screen> -</informalexample> - -<para> If you need to edit the disklabel to create multiple -partitions (such as swap), use the following: </para> - -<informalexample> -<screen> -<userinput> - dd if=/dev/zero of=/dev/rwd2 count=2 - disklabel /dev/r$d > /tmp/label - # Edit disklabel to add partitions: - vi /tmp/label - disklabel -B -R -r wd2 /tmp/label - # newfs partitions appropriately -</userinput> -</screen> -</informalexample> - -<para>Your disk is now ready for use.</para> - -</sect1> -</chapter> - -<chapter> -<title>Making Compatibility Mode Disks</title> - -<sect1> -<title>Introduction</title> -<para>The command line is the easiest way to make dedicated disks, and -the worst way to make compatibility disks. The command-line fdisk -utility requires higher math skills and an in-depth understanding of -the slice table, which is more than most people want to deal with. -Use sysinstall for compatibility disks, as described below.</para> - -</sect1> -<sect1> - -<title>Making Compatibility Mode Disks Using Sysinstall</title> - -<orderedlist> -<listitem><para>Start sysinstall as root by typing -<informalexample> -<screen><userinput>/stand/sysinstall</></screen> -</informalexample> -from the command prompt.</para></listitem> - -<listitem><para>Select <command>Index</command>.</para> </listitem> -<listitem><para>Select <command>Partition</command>.</para></listitem> -<listitem><para>Select the disk to edit with arrow keys and -<keycap>SPACE</keycap>. -</para></listitem> -<listitem><para>If you are using this entire disk for FreeBSD, select -<command>A</command>.</para></listitem> - -<listitem><para>When asked: -<informalexample> -<screen> -Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? -</screen> -</informalexample> answer <command>yes</command>.</para></listitem> -<listitem><para>Select <command>Write</command>.</para></listitem> -<listitem><para>When asked to install the boot manager, select None with -<keycap>SPACE</keycap> then hit <keycap>ENTER</keycap> for OK.</para></listitem> -<listitem><para><command>Quit</command> the FDISK Editor.</para></listitem> -<listitem><para>You'll be asked about the boot manager, select -<command>None</command> -again. </para></listitem> -<listitem><para>Select <command>Label</command> from the Index -menu.</para></listitem> -<listitem><para>Label as desired. For a single partition, accept the -default size, type filesystem, and a mountpoint (which isn't -used).</para></listitem> -<listitem><para>The filesystem will be newfs'd for you, unless you select otherwise (for news partitions you'll want to do this!). You'll get the error: -<informalexample> -<screen> -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory </screen> -</informalexample> -Ignore. -</para></listitem> -<listitem><para>Exit out by repeatedly pressing <keycap>ESCAPE</keycap>.</para></listitem> -</orderedlist> - -<para>Your new disk is now ready for use.</para> - -</sect1> -</chapter> - -<chapter> -<title>Other Disk Operations</title> -<sect1> -<title>Adding Swap Space</title> - -<para>As a system grows, it's need for swap space can also grow. -Although adding swap space to existing disks is very difficult, a new -disk can be partitioned with additional swap space. </para> - -<para>To add swap space when adding a disk to a system: -<orderedlist> -<listitem><para>When partitioning the disk, edit the disklabel and -allocate the amount of swap space to add in partition `b' and the -remainder in another partition, such as `a' or `e'. The size is given -in 512 byte blocks. </para></listitem> -<listitem><para>When newfsing the drive, do NOT newfs the `c' -partition. Instead, newfs the partition where the non-swap space -lies.</para></listitem> -<listitem><para>Add an entry to <filename>/etc/fstab</filename> as follows: -<informalexample> -<programlisting> -/dev/wd0b none swap sw 0 0 -</programlisting> -</informalexample> -Change /dev/wd0b to the device of the newly added -space.</para></listitem> -<listitem><para>To make the new space immediately available, use the -<command>swapon</command> command. -<informalexample> -<screen> -<userinput> -$ swapon /dev/sd0b -</userinput> -swapon: added /dev/sd0b as swap space -</screen> -</informalexample> -</para></listitem> -</orderedlist> -</para> -</sect1> - -<sect1> -<title>Copying the Contents of Disks</title> -<!-- Should have specific tag --> -<para>Submitted By: Renaud Waldura (<email>renaud@softway.com</email>) </para> - -<para>To move file from your original base disk to the fresh new one, -do: -<informalexample> -<screen> -<userinput> -mount /dev/wd2 /mnt -pax -r -w -p e /usr/home /mnt -umount /mnt -rm -rf /usr/home/* -mount /dev/wd2 /usr/home -</userinput> -</screen> -</informalexample> -</para> -</sect1> - -<sect1> -<title>Creating Striped Disks using CCD</title> -<para>Commands Submitted By: Stan Brown (<email>stanb@awod.com</email>) </para> - -<para> -The Concatenated Disk Driver, or CCD, allows you to treat several identical disks as a single disk. -Striping can result in increased disk performance by distributing reads and -writes across the disks. See the ccd(4) and ccdconfig(4) man pages or the -<ulink URL="http://stampede.cs.berkeley.edu/ccd/">CCD Homepage</ulink> for further details.</para> - -<para>To create a new CCD, execute the following commands. This describes -how to add three disks together; simply add or remove devices as -necessary. Remember that the disks to be striped must be <emphasis>identical.</></para> - -<para>Before executing these commands, make sure you add the line -<userinput> -pseudo-device ccd 4 -</userinput> - -to your kernel.</para> - -<informalexample> -<screen> -<userinput> -cd /dev ; sh MAKDEV ccd0 - -disklabel -r -w sd0 auto -disklabel -r -w sd1 auto -disklabel -r -w sd2 auto - -disklabel -e sd0c # change type to 4.2BSD -disklabel -e sd1c # change type to 4.2BSD -disklabel -e sd2c # change type to 4.2BSD - -ccdconfig ccd0 32 0 /dev/sd0c /dev/sd1c /dev/sd2c - -newfs /dev/rccd0c -</userinput> -</screen> -</informalexample> - -<para>Now you can mount and use your CCD by referencing device /dev/ccd0c. -</para> - -</sect1> -</chapter> - -<chapter> -<title>Credits</title> - - - -<para>The author would like to thank the following individuals for -their contributions to this project: -<itemizedlist> -<listitem><para>Darryl Okahata -(<email>darrylo@hpnmhjw.sr.hp.com</email>) for his -simple dedicated mode setup documentation which I have used repeatedly -on freebsd-questions.</para></listitem> -<listitem><para>Jordan Hubbard -(<email>jkh@freebsd.org</email>) for making -sysinstall useful for this type of task.</para></listitem> -<listitem><para>John Fieber -(<email>jfieber@indiana.edu</email>) for making -information and examples of the DocBook DTD on which this document is -based.</para></listitem> -<listitem><para>Greg Lehey (<email>grog@freebsd.org</email>) for checking my -work and pointing out inaccuracies, as well as miscellaneous support. -</para></listitem> -</itemizedlist> -</para> - -</chapter> - - - -</book> diff --git a/en/tutorials/disklessx/Makefile b/en/tutorials/disklessx/Makefile deleted file mode 100644 index 1f97515c64..0000000000 --- a/en/tutorials/disklessx/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -# $Id: Makefile,v 1.3 1998-08-24 23:43:17 wosch Exp $ - -DOCS= disklessx.docb - -.include "../../web.mk" diff --git a/en/tutorials/disklessx/disklessx.docb b/en/tutorials/disklessx/disklessx.docb deleted file mode 100644 index 9e3ddc2d10..0000000000 --- a/en/tutorials/disklessx/disklessx.docb +++ /dev/null @@ -1,287 +0,0 @@ -<!-- $Id: disklessx.docb,v 1.1 1998-08-24 23:43:17 wosch Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> -<bookinfo> -<bookbiblio> - -<title>Diskless X Server: a how to guide</title> - -<authorgroup> -<author> -<firstname> Jerry</firstname> -<surname>Kendall</surname> -<affiliation> -<address> -<email>jerry@kcis.com</email> -</address> -</affiliation> -</author></authorgroup> - -<pubdate>28-December-1996</pubdate> - -<copyright> -<year>1996</year> -<holder>Jerry Kendall</holder> -</copyright> - - -<abstract><para> -With the help of some 'friends' on the FreeBSD-hackers list, I have -been able to create a diskless X terminal... The creation of the X terminal -required first creating a diskless system with minimal utilities mounted -via NFS. These same steps were used to create 2 separate diskless systems. -The first is 'altair.kcis.com'. A diskless X terminal that I run on my -old 386DX-40. It has a 340Meg hard disk but, I did not want to change it. -So, it boots from 'antares.kcis.com' across a Ethernet. The second system -is a 486DX2-66. I setup a diskless FreeBSD (complete) that uses no local -disk. The server in that case is a Sun 670MP running -SunOS 4.1.3. The same setup configuration was needed for both. -</para> - -<para> -NOTE: I am sure that there is stuff that needs to be added to this. Please send me any comments.... -</para> - -</abstract> - - -</bookbiblio> -</bookinfo> - - -<chapter><title>Creating the boot floppy (On the diskless system)</title> - -<para>Since the network boot loaders will not work with some of -the TSR's and such that MS-DOS uses, it is best to create -a dedicated boot floppy OR, if you can, create an MS-DOS menu -that will (via the config.sys/autoexec.bat files) ask what -configuration to load when the system starts. The later is the -method that I use and it works great. My MS-DOS (6.x) menu is below.</para> -<informalexample><screen> - ---- config.sys ---- - [menu] - menuitem=normal, normal - menuitem=unix, unix - [normal] - .... - normal config.sys stuff - ... - [unix] - ---- - - ---- autoexec.bat ---- - @ECHO OFF - goto %config% - - :normal - ... - normal autoexec.bat stuff - ... - goto end - - :unix - cd \netboot - nb8390.com - - :end - ---- -</screen></informalexample> -</chapter> - -<chapter><title>Getting the network boot programs (On the server)</title> - -<para>Compile the 'net-boot' programs that are located in -/usr/src/sys/i386/boot/netboot. You should read the comments -at the top of the makefile. Adjust as required. !!!! make a -backup of the original in case it gets fobar'd !!! When the build -is done, there should be 2 MS-DOS executables, 'nb8390.com' and -'nb3c509.com'. One of these two programs will be what you need -to run on the diskless server. It will load the kernel from the -boot server. At this point, put both programs on the MS-DOS -boot floppy created earlier.</para> -</chapter> - -<chapter><title>Determine which program to run (On the diskless system)</title> - -<para>If you know the chipset that your Ethernet adapter uses, this is -easy. If you have the NS8390 chipset, or a NS8390 based chipset, -use NB8390.COM. If you have a 3Com 509 based chipset, use the -NB3C509.COM boot program. If you are not sure which you have, -try using one, if it says 'No adapter found', try the other. -Beyond that, you are pretty much on your own.</para> -</chapter> - -<chapter><title>Booting across the network</title> - -<para>Boot the diskless system with out any config.sys/autoexec.bat -files. try running the boot program for your Ethernet adapter.</para> -<informalexample><screen> - My Ethernet adapter is running in WD8013 16bit mode so - I run NB8390.COM - - C:> cd \netboot - C:> nb8390 - - Boot from Network (Y/N) ? Y - - BOOTP/TFTP/NFS bootstrap loader ESC for menu - - Searching for adapter.. - WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66 - - Searching for server..</screen></informalexample> - -<para>At this point, my diskless system is trying to find a machine to act -as a boot server. Make note of the addr line above, you will need this -number later. Reset the diskless system and modify your config.sys and -autoexec.bat files to do these steps automatically for you. Perhaps in -a menu. If you had to run 'nb3c509.com' instead of 'nb8390.com' the -output is the same as above. If you got 'No adapter found' at the -'Searching for adapter..' message, verify that you did indeed set the -compile time defines in the makefile correctly.</para> - -</chapter> -<chapter><title>Allowing systems to boot across the network (On the - server)</title> - -<para>Make sure the /etc/inetd.conf file has entries for tftp and bootps. -Mine are listed below:</para> -<informalexample><screen> - ---- /etc/inetd.conf ---- - tftp dgram udp wait nobody /usr/libexec/tftpd tftpd - # - # Additions by who ever you are - bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab - ---- -</screen></informalexample> -<para>If you have to change the /etc/inetd.conf file, send a HUP signal to -inetd. To do this, get the process ID of inetd with 'ps -ax | grep -inetd | grep -v grep'. Once you have it, send it a HUP signal. Do this -by 'kill -HUP <pid>'. This will force inetd to re-read its config file.</para> - -<para>Did you remember to note the 'addr' line from the output of the boot -loader on the diskless system???? Guess what, here is where you need it.</para> - -<para>Add an entry to /etc/bootptab (maybe creating the file). It should be -laid out identical to this:</para> - -<informalexample><screen> - altair:\ - :ht=ether:\ - :ha=004001432666:\ - :sm=255.255.255.0:\ - :hn:\ - :ds=199.246.76.1:\ - :ip=199.246.76.2:\ - :gw=199.246.76.1:\ - :vm=rfc1048: - - The lines are as follows: - 'altair' the diskless systems name without the domain name. - 'ht=ether' the hardware type of 'ethernet'. - 'ha=004001432666' the hardware address (the number noted above). - 'sm=255.255.255.0' the subnet mask. - 'hn' tells server to send client's hostname to the client. - 'ds=199.246.76.1' tells the client who the domain server is. - 'ip=199.246.76.2' tells the client what it's IP address is. - 'gw=199.246.76.1' tells the client what the default gateway is. - 'vm=...' just leave it there... -</screen></informalexample> -<para>NOTE: -****** Be sure to setup the IP addresses correctly, the addresses -above are my own......</para> - -<para>Create the directory '/tftpboot' on the server it will contain the -configuration files for the diskless systems that the server will -serve. These files will be named 'cfg.<ip>' where <ip> is the IP -address of the diskless system. The config file for 'altair' is -/tftpboot/cfg.199.246.76.2. The contents is:</para> - -<informalexample><screen> - ---- /tftpboot/cfg.199.246.76.2 ---- - rootfs 199.246.76.1:/DiskLess/rootfs/altair - hostname altair.kcis.com - ---- -</screen></informalexample> -<para>The line 'hostname altair.kcis.com' simply tells the diskless -system what its fully qualified domain name is.</para> - -<para>The line 'rootfs 199.246.76.1:/DiskLess/rootfs/altair' tells the -diskless system where its NFS mountable root filesystem is located.</para> - -<para>NOTE:!!!!! The NFS mounted root filesystem will be mounted READ ONLY.</para> - -<para>The hierarchy for the diskless system can be re-mounted allowing -read-write operations if required.</para> - -<para>I use my spare 386DX-40 as a dedicated X terminal...</para> - -<para>The hierarchy for 'altair' is:</para> - -<informalexample><screen> - / - /bin - /etc - /tmp - /sbin - /dev - /dev/fd - /usr - /var - /var/run -</screen></informalexample> - -<para>The actual list of files is:</para> - -<informalexample><screen> - -r-xr-xr-x 1 root wheel 779984 Dec 11 23:44 ./kernel - -r-xr-xr-x 1 root bin 299008 Dec 12 00:22 ./bin/sh - -rw-r--r-- 1 root wheel 499 Dec 15 15:54 ./etc/rc - -rw-r--r-- 1 root wheel 1411 Dec 11 23:19 ./etc/ttys - -rw-r--r-- 1 root wheel 157 Dec 15 15:42 ./etc/hosts - -rw-r--r-- 1 root bin 1569 Dec 15 15:26 ./etc/XF86Config.altair - -r-x------ 1 bin bin 151552 Jun 10 1995 ./sbin/init - -r-xr-xr-x 1 bin bin 176128 Jun 10 1995 ./sbin/ifconfig - -r-xr-xr-x 1 bin bin 110592 Jun 10 1995 ./sbin/mount_nfs - -r-xr-xr-x 1 bin bin 135168 Jun 10 1995 ./sbin/reboot - -r-xr-xr-x 1 root bin 73728 Dec 13 22:38 ./sbin/mount - -r-xr-xr-x 1 root wheel 1992 Jun 10 1995 ./dev/MAKEDEV.local - -r-xr-xr-x 1 root wheel 24419 Jun 10 1995 ./dev/MAKEDEV -</screen></informalexample> -<para>Don't forget to 'MAKEDEV all' in the 'dev' directory.</para> - -<para>My /etc/rc for 'altair' is:</para> - -<informalexample><screen> - #!/bin/sh - # - PATH=/bin:/sbin - export PATH - # - # configure the localhost - /sbin/ifconfig lo0 127.0.0.1 - # - # configure the ethernet card - /sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00 - # - # mount the root filesystem via NFS - /sbin/mount antares:/DiskLess/rootfs/altair / - # - # mount the /usr filesystem via NFS - /sbin/mount antares:/DiskLess/usr /usr - # - /usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1 - # - # Reboot after X exits - /sbin/reboot - # - # We blew up.... - exit 1 -</screen></informalexample> - -<para>Any comments and ALL questions welcome....</para> - -</chapter> -</book> diff --git a/en/tutorials/doc.ftr b/en/tutorials/doc.ftr deleted file mode 100644 index 16fd1d4be1..0000000000 --- a/en/tutorials/doc.ftr +++ /dev/null @@ -1,5 +0,0 @@ -<hr> -<address> - <a href="../../mailto.html">freebsd-questions@freebsd.org</a> -</address> - diff --git a/en/tutorials/doc.hdr b/en/tutorials/doc.hdr deleted file mode 100644 index 76a9b276cd..0000000000 --- a/en/tutorials/doc.hdr +++ /dev/null @@ -1,14 +0,0 @@ -<IMG SRC="../../gifs/bar.gif" ALT="" WIDTH="565" HEIGHT="33" BORDER=0 usemap="#bar"> -<map name="bar"> -<area shape="rect" coords="1,1,111,31" href="../../index.html" ALT=""> -<area shape="rect" coords="112,11,196,31" href="../../ports/index.html" ALT=""> -<area shape="rect" coords="196,12,257,33" href="../../support.html" ALT=""> -<area shape="rect" coords="256,12,365,33" href="../../docs.html" ALT=""> -<area shape="rect" coords="366,13,424,32" href="../../commercial/commercial.html" ALT=""> -<area shape="rect" coords="425,16,475,32" href="../../search/search.html" ALT=""> -<area shape="rect" coords="477,16,516,33" href="../../search/index-site.html" ALT=""> -<area shape="rect" coords="516,15,562,33" href="../../index.html" ALT=""> -<area shape="rect" href="../../index.html" coords="0,0,564,32" ALT=""> -</map> - -<br clear=all> diff --git a/en/tutorials/docproj-primer/Makefile b/en/tutorials/docproj-primer/Makefile deleted file mode 100644 index 721b5e366f..0000000000 --- a/en/tutorials/docproj-primer/Makefile +++ /dev/null @@ -1,41 +0,0 @@ -# -# $Id: Makefile,v 1.3 1999-07-14 22:31:29 nik Exp $ -# -# Build the FreeBSD Documentation Project Primer. -# - -MAINTAINER=nik@FreeBSD.ORG - -DOC?= book - -FORMATS?= html-split html - -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= book.sgml -SRCS+= overview/chapter.sgml -SRCS+= psgml-mode/chapter.sgml -SRCS+= see-also/chapter.sgml -SRCS+= sgml-markup/chapter.sgml -SRCS+= sgml-primer/chapter.sgml -SRCS+= stylesheets/chapter.sgml -SRCS+= the-faq/chapter.sgml -SRCS+= the-handbook/chapter.sgml -SRCS+= the-website/chapter.sgml -SRCS+= tools/chapter.sgml -SRCS+= translations/chapter.sgml -SRCS+= writing-style/chapter.sgml - -# Entities -SRCS+= chapters.ent - -DOC_PREFIX?= ../../.. - -.include "../../../share/mk/docproj.docbook.mk" diff --git a/en/tutorials/docproj-primer/book.sgml b/en/tutorials/docproj-primer/book.sgml deleted file mode 100644 index c1e35d9953..0000000000 --- a/en/tutorials/docproj-primer/book.sgml +++ /dev/null @@ -1,281 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: book.sgml,v 1.5 1999-07-14 22:31:28 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 % chapters SYSTEM "chapters.ent"> %chapters; -]> - -<book> - <bookinfo> - <title>FreeBSD Documentation Project Primer for New Contributors</title> - - <author> - <firstname>Nik</firstname> - <surname>Clayton</surname> - <affiliation> - <address><email>nik@FreeBSD.ORG</email></address> - </affiliation> - </author> - - <copyright> - <year>1998</year> - <year>1999</year> - <holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder> - </copyright> - - <pubdate role="rcs">$Date: 1999-07-14 22:31:28 $</pubdate> - - <releaseinfo>$Id: book.sgml,v 1.5 1999-07-14 22:31:28 nik Exp $</releaseinfo> - - <legalnotice> - <para>Redistribution and use in source (SGML DocBook) and 'compiled' - forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions are - met:</para> - - <orderedlist> - <listitem> - <para>Redistributions of source code (SGML DocBook) must retain the - above copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified.</para> - </listitem> - - <listitem> - <para>Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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.</para> - </listitem> - </orderedlist> - - <important> - <para>THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 - DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH - DAMAGE.</para> - </important> - </legalnotice> - - <abstract> - <para>Thank you for becoming a part of the FreeBSD Documentation - Project. Your contribution is extremely valuable.</para> - - <para>This primer covers everything you will need to know in order - to start contributing to the FreeBSD Documentation Project, from - the tools and software you will be using (both mandatory and - recommended) to the philosophy behind the Documentation - Project.</para> - - <para>This document is a work in progress, and is not complete. Sections - that are known to be incomplete are indicated with a - <literal>*</literal> in their name.</para> - </abstract> - </bookinfo> - - <preface> - <title>Preface</title> - - <sect1> - <title>Shell Prompts</title> - - <para>The following table shows the default system prompt and superuser - prompt. The examples will use this prompt to indicate which user you - should be running the example as.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>User</entry> - <entry>Prompt</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Normal user</entry> - <entry>&prompt.user;</entry> - </row> - - <row> - <entry><username>root</username></entry> - <entry>&prompt.root;</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1> - <title>Typographic Conventions</title> - - <para>The following table describes the typographic conventions used in - this book.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Meaning</entry> - <entry>Examples</entry> - </row> - </thead> - - <tbody> - <row> - <entry>The name of commands, files, and directories. On screen - computer output.</entry> - <entry><para>Edit your <filename>.login</filename> - file.</para><para>Use <command>ls -a</command> to list all - files.</para><para><screen>You have mail.</screen> - </para></entry> - </row> - - <row> - <entry>What you type, when contrasted with on-screen computer - output.</entry> - - <entry><screen>&prompt.user; <userinput>su</userinput> -Password:</screen></entry> - </row> - - <row> - <entry>Manual page references.</entry> - - <entry>Use <citerefentry> - <refentrytitle>su</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> to change user names.</entry> - </row> - - <row> - <entry>User and group names</entry> - - <entry>Only <username>root</username> can do this.</entry> - </row> - - <row> - <entry>Emphasis</entry> - - <entry>You <emphasis>must</emphasis> do this.</entry> - </row> - - <row> - <entry>Command line variables; replace with the real name or - variable.</entry> - - <entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry> - </row> - - <row> - <entry>Environment variables</entry> - - <entry><envar>$HOME</envar> is your home directory.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1> - <title>Notes, warnings, and examples</title> - - <para>Within the text appear notes, warnings, and examples.</para> - - <note> - <para>Notes are represented like this, and contain information that - you should take note of, as it may affect what you do.</para> - </note> - - <warning> - <para>Warnings are represented like this, and contain information - warning you about possible damage if you do not follow the - instructions. This damage may be physical, to your hardware or to - you, or it may be non-physical, such as the inadvertant deletion of - important files.</para> - </warning> - - <example> - <title>A sample example</title> - - <para>Examples are represented like this, and typically contain - examples you should walk through, or show you what the results of a - particular action should be.</para> - </example> - </sect1> - - <sect1> - <title>Acknowledgments</title> - - <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter - Flynn, and Christopher Maden, who took the time to read early drafts - of this document and offer many valuable comments and - criticisms.</para> - </sect1> - </preface> - - &chap.overview; - &chap.tools; - &chap.sgml-primer; - &chap.sgml-markup; - &chap.stylesheets; - &chap.the-faq; - &chap.the-handbook; - &chap.the-website; - &chap.translations; - &chap.writing-style; - &chap.psgml-mode; - &chap.see-also; - -</book> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en/tutorials/docproj-primer/chapter.decl b/en/tutorials/docproj-primer/chapter.decl deleted file mode 100644 index ce0a7ed16a..0000000000 --- a/en/tutorials/docproj-primer/chapter.decl +++ /dev/null @@ -1 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> diff --git a/en/tutorials/docproj-primer/chapters.ent b/en/tutorials/docproj-primer/chapters.ent deleted file mode 100644 index 3375e0085d..0000000000 --- a/en/tutorials/docproj-primer/chapters.ent +++ /dev/null @@ -1,23 +0,0 @@ -<!-- - Creates entities for each chapter in the Documentation Project Primer. - 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.2 1999-07-14 22:31:29 nik Exp $ ---> - -<!ENTITY chap.overview SYSTEM "overview/chapter.sgml"> -<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml"> -<!ENTITY chap.tools SYSTEM "tools/chapter.sgml"> -<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml"> -<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml"> -<!ENTITY chap.the-faq SYSTEM "the-faq/chapter.sgml"> -<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml"> -<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml"> -<!ENTITY chap.translations SYSTEM "translations/chapter.sgml"> -<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml"> -<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml"> -<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml"> diff --git a/en/tutorials/docproj-primer/overview/chapter.sgml b/en/tutorials/docproj-primer/overview/chapter.sgml deleted file mode 100644 index 1322c34a6f..0000000000 --- a/en/tutorials/docproj-primer/overview/chapter.sgml +++ /dev/null @@ -1,179 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.2 1999-07-14 19:25:40 nik Exp $ ---> - -<chapter id="overview"> - <title>Overview</title> - - <para>Welcome to the FreeBSD Documentation Project. Good quality - documentation is very important to the success of FreeBSD, and the - FreeBSD Documentation Project (FDP) is how a lot of that documentation - is produced. Your contributions are very valuable.</para> - - <para>This document's main purpose is to clearly explain <emphasis>how - the FDP is organised</emphasis>, <emphasis>how to write and submit - documentation to the FDP</emphasis>, and <emphasis>how to - effectively use the tools available to you when writing - documentation</emphasis>.</para> - - <para>Every one is welcome to join the FDP. There is no minimum - membership requirements, no quota of documentation you need to - produce per month. All you need to do is subscribe to the - <email>freebsd-doc@freebsd.org</email> mailing list.</para> - - <para>After you have finished reading this document you should:</para> - - <itemizedlist> - <listitem> - <para>Know which documentation is maintained by the FDP.</para> - </listitem> - - <listitem> - <para>Be able to read and understand the SGML source code for the - documentation maintained by the FDP.</para> - </listitem> - - <listitem> - <para>Be able to make changes to the documentation.</para> - </listitem> - - <listitem> - <para>Be able to submit your changes back for review and eventual - inclusion in the FreeBSD documentation.</para> - </listitem> - </itemizedlist> - - <sect1> - <title>The FreeBSD Documentation Set</title> - - <para>The FDP is responsible for four categories of FreeBSD - documentation.</para> - - <variablelist> - <varlistentry> - <term>Manual pages</term> - - <listitem> - <para>The English language system manual pages are not written by - the FDP, as they are part of the base system. However, the FDP can - (and has) re-worded parts of existing manual pages to make them - clearer, or to correct inaccuracies.</para> - - <para>The translation teams are responsible for translating the - system manual pages in to different languages. These translations - are kept within the FDP.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FAQ</term> - - <listitem> - <para>The FAQ aims to address (in short question and answer format) - questions that are asked, or should be asked, on the various - mailing lists and newsgroups devoted to FreeBSD. The format does - not permit long and comprehensive answers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook</term> - - <listitem> - <para>The Handbook aims to be the comprehensive on-line resource and - reference for FreeBSD users.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Web site</term> - - <listitem> - <para>This is the main FreeBSD presence on the World Wide Web, - visible at <ulink - url="http://www.freebsd.org/">http://www.freebsd.org/</ulink> - and many mirrors around the world. The web site is many people's - first exposure to FreeBSD.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>These four groups of documentation are all available in the - FreeBSD CVS tree. This means that the logs and changes to these - files are visible to anyone, and anyone can use a program such as - <application>CVSup</application> or - <application>CTM</application> to keep their own local copies of - this documentation.</para> - - <para>In addition, many people have written tutorials or other web - sites relating to FreeBSD. Some of these are stored in the CVS - repository as well (where the author has agreed to this). In - other cases the author has decided to keep their documentation - separate from the main FreeBSD repository. The FDP endeavours to - provide links to as much of this documentation as - possible.</para> - </sect1> - - <sect1> - <title>Before you start</title> - - <para>This document assumes that you already know:</para> - - <itemizedlist> - <listitem> - <para>How to maintain an up-to-date local copy of the FreeBSD - documentation. Either by maintaining a local copy of the - FreeBSD CVS repository (using <application>CVS</application> - and either <application>CVSup</application> or - <application>CTM</application>) or by using - <application>CVSup</application> to download just a - <emphasis>checked-out</emphasis> copy.</para> - </listitem> - - <listitem> - <para>How to download and install new software using either the - FreeBSD Ports system or &man.pkg.add.1;.</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: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en/tutorials/docproj-primer/psgml-mode/chapter.sgml b/en/tutorials/docproj-primer/psgml-mode/chapter.sgml deleted file mode 100644 index 6dc06189f6..0000000000 --- a/en/tutorials/docproj-primer/psgml-mode/chapter.sgml +++ /dev/null @@ -1,150 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.2 1999-07-14 19:17:50 nik Exp $ ---> - -<chapter id="psgml-mode"> - <title>Using <literal>sgml-mode</literal> with - <application>Emacs</application></title> - - <para>Recent versions of Emacs or Xemacs (available from the ports - collection) contain a very useful package called PSGML. Automatically - invoked when a file with <filename>.sgml</filename> extension is loaded, - or by typing <command>M-x sgml-mode</command>, it is a major mode for - dealing with SGML files, elements and attributes.</para> - - <para>An understanding of some of the commands provided by this mode can - make working with SGML documents such as the Handbook much easier.</para> - - <variablelist> - <varlistentry> - <term><command>C-c C-e</command></term> - - <listitem> - <para>Runs <literal>sgml-insert-element</literal>. You will be - prompted for the name of the element to insert at the current point. - You can use the TAB key to complete the element. Elements that are - not valid at the current point will be disallowed.</para> - - <para>The start and end tags for the element will be inserted. If the - element contains other, mandatory, elements then these will be - inserted as well.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c =</command></term> - - <listitem> - <para>Runs <literal>sgml-change-element-name</literal>. Place the - point within an element and run this command. You will be prompted - for the name of the element to change to. Both the start and end - tags of the current element will be changed to the new - element.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-r</command></term> - - <listitem> - <para>Runs <literal>sgml-tag-region</literal>. Select some text (move - to start of text, C-space, move to end of text, C-space) and then - run this command. You will be prompted for the element to use. This - element will then be inserted immediately before and after your - marked region.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c -</command></term> - - <listitem> - <para>Runs <literal>sgml-untag-element</literal>. Place the point - within the start or end tag of an element you want to remove, and - run this command. The element's start and end tags will be - removed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-q</command></term> - - <listitem> - <para>Runs <literal>sgml-fill-element</literal>. Will recursively fill - (i.e., reformat) content from the current element in. The filling - <emphasis>will</emphasis> affect content in which whitespace is - significant, such as within <sgmltag>programlisting</sgmltag> - elements, so run this command with care.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-a</command></term> - - <listitem> - <para>Runs <literal>sgml-edit-attributes</literal>. Opens a second - buffer containing a list of all the attributes for the closest - enclosing element, and their current values. Use TAB to navigate - between attributes, <command>C-k</command> to remove an existing - value and replace it with a new one, <command>C-c</command> to close - this buffer and return to the main document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-v</command></term> - - <listitem> - <para>Runs <literal>sgml-validate</literal>. Prompts you to save the - current document (if necessary) and then runs an SGML validator. The - output from the validator is captured into a new buffer, and you can - then navigate from one troublespot to the next, fixing markup errors - as you go.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Doubtless there are other useful functions of this mode, but those are - the ones I use most often.</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: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en/tutorials/docproj-primer/see-also/chapter.sgml b/en/tutorials/docproj-primer/see-also/chapter.sgml deleted file mode 100644 index 2ede72da78..0000000000 --- a/en/tutorials/docproj-primer/see-also/chapter.sgml +++ /dev/null @@ -1,121 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.2 1999-07-14 19:27:14 nik Exp $ ---> - -<chapter id="see-also"> - <title>See Also</title> - - <para>This document is deliberately not an exhaustive discussion of SGML, - the DTDs listed, and the FreeBSD Documentation Project. For more - information about these, you are encouraged to see the following web - sites.</para> - - <sect1> - <title>The FreeBSD Documentation Project</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.freebsd.org/docproj/">The FreeBSD - Documentation Project web pages</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.freebsd.org/handbook/">The FreeBSD Handbook</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>SGML</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web - page</ulink>, a comprehensive SGML resource</para> - </listitem> - - <listitem> - <para><ulink - url='http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG'>Gentle introduction to SGML</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>HTML</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.w3.org/">The World Wide Web - organisation</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0 - specification</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>DocBook</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.oreilly.com/davenport/">The Davenport - Group</ulink>, maintainers of the DocBook DTD</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>The Linux Documentation Project</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://metalab.unc.edu/LDP/">The Linux Documentation - Project web pages</ulink></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: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en/tutorials/docproj-primer/sgml-markup/chapter.sgml b/en/tutorials/docproj-primer/sgml-markup/chapter.sgml deleted file mode 100644 index 8a8c216754..0000000000 --- a/en/tutorials/docproj-primer/sgml-markup/chapter.sgml +++ /dev/null @@ -1,2213 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.5 1999-07-30 20:51:01 nik Exp $ ---> - -<chapter id="sgml-markup"> - <title>SGML Markup</title> - - <para>This chapter describes the three markup languages you will encounter - when you contribute to the FreeBSD documentation project. Each section - describes the markup language, and details the markup that you are likely - to want to use, or that is already in use.</para> - - <para>These markup languages contain a large number of elements, and it can - be confusing sometimes to know which element to use for a particular - situation. This section goes through the elements you are most likely to - need, and gives examples of how you would use them.</para> - - <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since - that would just reiterate the documentation for each language. The aim of - this section is to list those elements more likely to be useful to you. - If you have a question about how best to markup a particular piece of - content, please post it to the FreeBSD Documentation Project mailing list - <email>freebsd-doc@freebsd.org</email>.</para> - - <note> - <title>Inline vs. block</title> - - <para>In the remainder of this document, when describing elements, - <emphasis>inline</emphasis> means that the element can occur within a - block element, and does not cause a line break. A - <emphasis>block</emphasis> element, by comparison, will cause a line - break (and other processing) when it is encountered.</para> - </note> - - <sect1> - <title>HTML</title> - - <para>HTML, the HyperText Markup Language, is the markup language of - choice on the World Wide Web. More information can be found at - <URL:<ulink - url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> - - <para>HTML is used to markup pages on the FreeBSD web site. It should not - (generally) be used to mark up other documention, since DocBook offers a - far richer set of elements to choose from. Consequently, you will - normally only encounter HTML pages if you are writing for the web - site.</para> - - <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the - latest, 4.0 (available in both <emphasis>strict</emphasis> and - <emphasis>loose</emphasis> variants).</para> - - <para>The HTML DTDs are available from the ports collection in the - <filename>textproc/html</filename> port. They are automatically - installed as part of the <filename>textproc/docproj</filename> - port.</para> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>There are a number of HTML FPIs, depending upon the version (also - known as the level) of HTML that you want to declare your document to - be compliant with.</para> - - <para>The majority of HTML documents on the FreeBSD web site comply with - the loose version of HTML 4.0.</para> - - <programlisting> -PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> - </sect2> - - <sect2> - <title>Sectional elements</title> - - <para>An HTML document is normally split in to two sections. The first - section, called the <emphasis>head</emphasis>, contains - meta-information about the document, such as its title, the name of - the author, the parent document, and so on. The second section, the - <emphasis>body</emphasis>, contains the content that will be displayed - to the user.</para> - - <para>These sections are indicated with <sgmltag>head</sgmltag> and - <sgmltag>body</sgmltag> elements respectively. These elements are - contained within the top-level <sgmltag>html</sgmltag> element.</para> - - <example> - <title>Normal HTML document structure</title> - - <programlisting> -<html> - <head> - <title><replaceable>The document's title</replaceable></title> - </head> - - <body> - - … - - </body> -</html></programlisting> - </example> - </sect2> - - <sect2> - <title>Block elements</title> - - <sect3> - <title>Headings</title> - - <para>HTML allows you to denote headings in your document, at up to - six different levels.</para> - - <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>, - then <sgmltag>h2</sgmltag>, continuing down to - <sgmltag>h6</sgmltag>.</para> - - <para>The element's content is the text of the heading.</para> - - <example> - <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<h1>First section</h1> - -<!-- Document introduction goes here --> - -<h2>This is the heading for the first section</h2> - -<!-- Content for the first section goes here --> - -<h3>This is the heading for the first sub-section</h3> - -<!-- Content for the first sub-section goes here --> - -<h2>This is the heading for the second section</h2> - -<!-- Content for the second section goes here -->]]></programlisting> - </example> - - <para>Generally, an HTML page should have one first level heading - (<sgmltag>h1</sgmltag>). This can contain many second level - headings (<sgmltag>h2</sgmltag>), which can in turn contain many - third level headings. Each - <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have - the same element, but one further up the hierarchy, preceeding it. - Leaving gaps in the numbering is to be avoided.</para> - - <example> - <title>Bad ordering of - <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<h1>First section</h1> - -<!-- Document introduction --> - -<h3>Sub-section</h3> - -<!-- This is bad, <h2> has been left out -->]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Paragraphs</title> - - <para>HTML supports a single paragraph element, - <sgmltag>p</sgmltag>.</para> - - <example> - <title><sgmltag>p</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>This is a paragraph. It can contain just about any - other element.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Block quotations</title> - - <para>A block quotation is an extended quotation from another document - that should not appear within the current paragraph.</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>A small excerpt from the US Constitution;</p> - -<blockquote>We the People of the United States, in Order to form - a more perfect Union, establish Justice, insure domestic - Tranquility, provide for the common defence, promote the general - Welfare, and secure the Blessings of Liberty to ourselves and our - Posterity, do ordain and establish this Constitution for the - United States of America.</blockquote>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Lists</title> - - <para>You can present the user with three types of lists, ordered, - unordered, and definition.</para> - - <para>Typically, each entry in an ordered list will be numbered, while - each entry in an unordered list will be proceeded by a bullet point. - Definition lists are composed of two sections for each entry. The - first section is the term being defined, and the second section is - the definition of the term.</para> - - <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> - element, unordered lists by the <sgmltag>ul</sgmltag> element, and - definition lists by the <sgmltag>dl</sgmltag> element.</para> - - <para>Ordered and unordered lists contain listitems, indicated by the - <sgmltag>li</sgmltag> element. A listitem can contain textual - content, or it may be further wrapped in one or more - <sgmltag>p</sgmltag> elements.</para> - - <para>Definition lists contain definition terms - (<sgmltag>dt</sgmltag>) and definition descriptions - (<sgmltag>dd</sgmltag>). A definition term can only contain inline - elements. A definition description can contain other block - elements.</para> - - <example> - <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>An unordered list. Listitems will probably be - preceeded by bullets.</p> - -<ul> - <li>First item</li> - - <li>Second item</li> - - <li>Third item</li> -</ul> - -<p>An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be - numbered.</p> - -<ol> - <li><p>This is the first item. It only has one paragraph.</p></li> - - <li><p>This is the first paragraph of the second item.</p> - - <p>This is the second paragraph of the second item.</p></li> - - <li><p>This is the first and only paragraph of the third - item.</p></li> -</ol>]]></programlisting> - </example> - - <example> - <title>Definition lists with <sgmltag>dl</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<dl> - <dt>Term 1</dt> - - <dd><p>Paragraph 1 of definition 1.</p></dd> - - <p>Paragraph 2 of definition 1.</p></dd> - - <dt>Term 2</dt> - - <dd><p>Paragraph 1 of definition 2.</p></dd> - - <dt>Term 3</dt> - - <dd>Paragraph 1 of definition 3. Note that the <p> - element is not required in the single paragraph case.</dd> -</dl>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Pre-formatted text</title> - - <para>You can indicate that text should be shown to the user exactly - as it is in the file. Typically, this means that the text is shown - in a fixed font, multiple spaces are not merged in to one, and line - breaks in the text are significant.</para> - - <para>In order to do this, wrap the content in the - <sgmltag>pre</sgmltag> element.</para> - - <example> - <title><sgmltag>pre</sgmltag></title> - - <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail - message;</para> - - <programlisting> -<![ CDATA [<pre> - From: nik@freebsd.org - To: freebsd-doc@freebsd.org - Subject: New documentation available - - There's a new copy of my primer for contributers to the FreeBSD - Documentation Project available at - - <URL:http://www.freebsd.org/~nik/primer/index.html> - - Comments appreciated. - - N -</pre>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Tables</title> - - <note> - <para>Most text-mode browsers (such as Lynx) do not render tables - particularly effectively. If you are relying on the tabular - display of your content, you should consider using alternative - markup to prevent confusion.</para> - </note> - - <para>Mark up tabular information using the <sgmltag>table</sgmltag> - element. A table consists of one or more table rows - (<sgmltag>tr</sgmltag>), each containing one or more cells of table - data (<sgmltag>td</sgmltag>). Each cell can contain other block - elements, such as paragraphs or lists. It can also contain another - table (this nesting can repeat indefinitely). If the cell only - contains one paragraph then you do not need to include the - <sgmltag>p</sgmltag> element.</para> - - <example> - <title>Simple use of <sgmltag>table</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>This is a simple 2x2 table.</p> - -<table> - <tr> - <td>Top left cell</td> - - <td>Top right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting></example> - - <para>A cell can span multiple rows and columns. To indicate this, - add the <literal>rowspan</literal> and/or <literal>colspan</literal> - attributes, with values indicating the number of rows of columns - that should be spanned.</para> - - <example> - <title>Using <literal>rowspan</literal></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>One tall thin cell on the left, two short cells next to - it on the right.</p> - -<table> - <tr> - <td rowspan="2">Long and thin</td> - </tr> - - <tr> - <td>Top cell</td> - - <td>Bottom cell</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Using <literal>colspan</literal></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>One long cell on top, two short cells below it.</p> - -<table> - <tr> - <td colspan="2">Top cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Using <literal>rowspan</literal> and - <literal>colspan</literal> together</title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of - cells merged in to one. The other cells are normal.</p> - -<table> - <tr> - <td colspan="2" rowspan="2">Top left large cell</td> - - <td>Top right cell</td> - </tr> - - <tr> - <!-- Because the large cell on the left merges in to - this row, the first <td> will occur on its - right --> - - <td>Middle right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom middle cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>In-line elements</title> - - <sect3> - <title>Emphasising information</title> - - <para>You have two levels of emphasis available in HTML, - <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>. - <sgmltag>em</sgmltag> is for a normal level of emphasis and - <sgmltag>strong</sgmltag> indicates stronger emphasis.</para> - - <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and - <sgmltag>strong</sgmltag> is rendered in bold. This is not always - the case however, and you should not rely on it.</para> - - <example> - <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p><em>This</em> has been emphasised, while - <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Bold and italics</title> - - <para>Because HTML includes presentational markup, you can also - indicate that particular content should be rendered in bold or - italic. The elements are <sgmltag>b</sgmltag> and - <sgmltag>i</sgmltag> respectively.</para> - - <example> - <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> - - <programlisting> -<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is - in italics.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Indicating fixed pitch text</title> - - <para>If you have content that should be rendered in a fixed pitch - (typewriter) typeface, use <sgmltag>tt</sgmltag> (for - “teletype”).</para> - - <example> - <title><sgmltag>tt</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>This document was originally written by - Nik Clayton, who can be reached by e-mail as - <tt>nik@freebsd.org</tt>.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Content size</title> - - <para>You can indicate that content should be shown in a larger or - smaller font. There are three ways of doing this.</para> - - <orderedlist> - <listitem> - <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag> - around the content you wish to change size. These tags can be - nested, so <literal><big><big>This is much - bigger</big></big></literal> is possible.</para> - </listitem> - - <listitem> - <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> - attribute set to <literal>+1</literal> or <literal>-1</literal> - respectively. This has the same effect as using - <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, - the use of this approach is deprecated.</para> - </listitem> - - <listitem> - <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> - attribute set to a number between 1 and 7. The default font size - is <literal>3</literal>. This approach is deprecated.</para> - </listitem> - </orderedlist> - - <example> - <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and - <sgmltag>font</sgmltag></title> - - <para>The following fragments all do the same thing.</para> - - <programlisting> -<![ CDATA [<p>This text is <small>slightly smaller</small>. But - this text is <big>slightly bigger</big>.</p> - -<p>This text is <font size="-1">slightly smaller</font>. But - this text is <font size="+1">slightly bigger</font.</p> - -<p>This text is <font size="2">slightly smaller</font>. But - this text is <font size="4">slightly bigger</font>.</p>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also in-line elements.</para> - </note> - - <sect3> - <title>Linking to other documents on the WWW</title> - - <para>In order to include a link to another document on the WWW you - must know the URL of the document you want to link to.</para> - - <para>The link is indicated with <sgmltag>a</sgmltag>, and the - <literal>href</literal> attribute contains the URL of the target - document. The content of the element becomes the link, and is - normally indicated to the user in some way (underlining, change of - colour, different mouse cursor when over the link, and so - on).</para> - - <example> - <title>Using <literal><a href="..."></literal></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>More information is available at the - <a href="http://www.freebsd.org/">FreeBSD web site</a>.</p>]]></programlisting> - </example> - - <para>These links will take the user to the top of the chosen - document.</para> - </sect3> - - <sect3> - <title>Linking to other parts of documents</title> - - <para>Linking to a point within another document (or within the same - document) requires that the document author include anchors that you - can link to.</para> - - <para>Anchors are indicated with <sgmltag>a</sgmltag> and the - <literal>name</literal> attribute instead of - <literal>href</literal>.</para> - - <example> - <title>Using <literal><a name="..."></literal></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced - in other links with the name <tt>para1</tt>.</p>]]></programlisting> - </example> - - <para>To link to a named part of a document, write a normal link to - that document, but include the name of the anchor after a - <literal>#</literal> symbol.</para> - - <example> - <title>Linking to a named part of another document</title> - - <para>Assume that the <literal>para1</literal> example resides in a - document called <filename>foo.html</filename>.</para> - - <programlisting> -<![ CDATA [<p>More information can be found in the - <a href="foo.html#para1">first paragraph</a> of - <tt>foo.html</tt>.</p>]]></programlisting> - </example> - - <para>If you are linking to a named anchor within the same document - then you can omit the document's URL, and just include the name of - the anchor (with the preceeding <literal>#</literal>).</para> - - <example> - <title>Linking to a named part of another document</title> - - <para>Assume that the <literal>para1</literal> example resides in - this document</para> - - <programlisting> -<![ CDATA [<p>More information can be found in the - <a href="#para1">first paragraph</a> of this - document.</p>]]></programlisting> - </example> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>DocBook</title> - - <para>DocBook was designed by the <ulink - url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be - a DTD for writing technical documentation. As such, and unlike LinuxDoc - and HTML, DocBook is very heavily orientated towards markup that - describes <emphasis>what</emphasis> something is, rather than describing - <emphasis>how</emphasis> it should be presented.</para> - - <note> - <title><literal>formal</literal> vs. <literal>informal</literal></title> - - <para>Some elements may exist in two forms, <emphasis>formal</emphasis> - and <emphasis>informal</emphasis>. Typically, the formal version of - the element will consist of a title followed by the information - version of the element. The informal version will not have a - title.</para> - </note> - - <para>The DocBook DTD is available from the ports collection in the - <filename>textproc/docbook</filename> port. It is automatically - installed as part of the <filename>textproc/docproj</filename> - port.</para> - - <sect2> - <title>FreeBSD extensions</title> - - <para>The FreeBSD Documentation Project has extended the DocBook DTD by - adding some new elements. These elements serve to make some of the - markup more precise.</para> - - <para>Where a FreeBSD specific element is listed below it is clearly - marked.</para> - - <para>Throughout the rest of this document, the term - “DocBook” is used to mean the FreeBSD extended DocBook - DTD.</para> - - <note> - <para>There is nothing about these extensions that is FreeBSD - specific, it was just felt that they were useful enhancements for - this particular project. Should anyone from any of the other *nix - camps (NetBSD, OpenBSD, Linux, …) be interested in - collaborating on a standard DocBook extension set, please get in - touch with Nik Clayton <email>nik@freebsd.org</email>.</para> - </note> - </sect2> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>In compliance with the DocBook guidelines for writing FPIs for - DocBook customisations, the FPI for the FreeBSD extended DocBook DTD - is;</para> - - <programlisting> -PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> - </sect2> - - <sect2> - <title>Sectional elements</title> - - <para>DocBook contains a number of elements for marking up the structure - of a book.</para> - - <para>Generally, the top level (first) element will be - <sgmltag>book</sgmltag>.</para> - - <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a - mandatory requirement. There may be <sgmltag>part</sgmltag>s between - the book and the chapter to provide another layer of organisation. - The Handbook is arranged in this way.</para> - - <para>A chapter may (or may not) contain one or more sections. These - are indicated with the <sgmltag>sect1</sgmltag> element. If a section - contains another section then use the <sgmltag>sect2</sgmltag> - element, and so on, up to <sgmltag>sect5</sgmltag>.</para> - - <para>Chapters and sections contain the remainder of the content.</para> - - <sect3> - <title>Starting a book</title> - - <para>The content of the book is contained within the - <sgmltag>book</sgmltag> element. As well as containing structural - markup, this element can contain elements that include additional - information about the book. This is either meta-information, used - for reference purposes, or additional content used to produce a - title page.</para> - - <para>This additional information should be contained within - <sgmltag>bookinfo</sgmltag>.</para> - - <example> - <title>Boilerplate <sgmltag>book</sgmltag> with - <sgmltag>bookinfo</sgmltag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting> -<book> - <bookinfo> - <title><replaceable>Your title here</replaceable></title> - - <author> - <firstname><replaceable>Your first name</replaceable></firstname> - <surname><replaceable>Your surname</replaceable></surname> - <affiliation> - <address><email><replaceable>Your e-mail address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <pubdate role="rcs">$Date$</pubdate> - - <releaseinfo>$Id$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> - </abstract> - </bookinfo> - - … - -</book></programlisting> - </example> - </sect3> - - <sect3> - <title>Indicating chapters</title> - - <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each - chapter has a mandatory <sgmltag>title</sgmltag>.</para> - - <example> - <title>A simple chapter</title> - - <programlisting> -<![ CDATA [<chapter> - <title>The chapter's title</title> - - ... -</chapter>]]></programlisting> - </example> - - <para>A chapter can not be empty, it must contain elements in addition - to <sgmltag>title</sgmltag>. If you need to include an empty - chapter then just use an empty paragraph.</para> - - <example> - <title>Empty chapters</title> - - <programlisting> -<![ CDATA [<chapter> - <title>This is an empty chapter</title> - - <para></para> -</chapter>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Sections below chapters</title> - - <para>Chapters can be broken up into sections, subsections, and so - on. Use the <sgmltag>sect<replaceable>n</replaceable></sgmltag> - element. The <replaceable>n</replaceable> indicates the section - number, which identifies the section level.</para> - - <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is - <sgmltag>sect1</sgmltag>. You can have one or more of these in a - chapter. They can contain one or more <sgmltag>sect2</sgmltag> - elements, and so on, down to <sgmltag>sect5</sgmltag>.</para> - - <example> - <title>Sections in chapters</title> - - <programlisting> -<![ CDATA [<chapter> - <title>A sample chapter</title> - - <para>Some text in the chapter.</para> - - <sect1> - <title>First section (1.1)</title> - - ... - </sect1> - - <sect1> - <title>Second section (1.2)</title> - - <sect2> - <title>First sub-section (1.2.1)</title> - - <sect3> - <title>First sub-sub-section (1.2.1.1)</title> - - ... - </sect3> - </sect2> - - <sect2> - <title>Second sub-section (1.2.2)</title> - - ... - </sect2> - </sect1> -</chapter>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Subdividing using <sgmltag>part</sgmltag>s</title> - - <para>You can introduce another layer of organisation between - <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or - more <sgmltag>part</sgmltag>s.</para> - - <programlisting> -<![ CDATA [<part> - <title>Introduction</title> - - <chapter> - <title>Overview</title> - - ... - </chapter> - - <chapter> - <title>What is FreeBSD?</title> - - ... - </chapter> - - <chapter> - <title>History</title> - - ... - </chapter> -</part>]]></programlisting> - </sect3> - </sect2> - - <sect2> - <title>Block elements</title> - - <sect3> - <title>Paragraphs</title> - - <para>DocBook supports three types of paragraphs; - <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and - <sgmltag>simpara</sgmltag>.</para> - - <para>Most of the time you will only need to use - <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a - <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag> - disallows some elements from within <sgmltag>para</sgmltag>. Stick - with <sgmltag>para</sgmltag>.</para> - - <example> - <title><sgmltag>para</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>This is a paragraph. It can contain just about any - other element.</para> ]]></programlisting> - - <para>Appearance:</para> - - <para>This is a paragraph. It can contain just about any other - element.</para> - </example> - </sect3> - - <sect3> - <title>Block quotations</title> - - <para>A block quotation is an extended quotation from another document - that should not appear within the current paragraph. You will - probably only need it infrequently.</para> - - <para>Blockquotes can optionally contain a title and an attribution - (or they can be left untitled and unattributed).</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>A small excerpt from the US Constitution;</para> - -<blockquote> - <title>Preamble to the Constitution of the United States</para> - - <attribution>Copied from a web site somewhere</attribution> - - <para>We the People of the United States, in Order to form a more perfect - Union, establish Justice, insure domestic Tranquility, provide for the - common defence, promote the general Welfare, and secure the Blessings - of Liberty to ourselves and our Posterity, do ordain and establish this - Constitution for the United States of America.</para> -</blockquote>]]></programlisting> - - <para>Appearance:</para> - - <blockquote> - <title>Preamble to the Constitution of the United States</title> - - <attribution>Copied from a web site somewhere</attribution> - - <para>We the People of the United States, in Order to form a more - perfect Union, establish Justice, insure domestic Tranquility, - provide for the common defence, promote the general Welfare, and - secure the Blessings of Liberty to ourselves and our Posterity, - do ordain and establish this Constitution for the United States - of America.</para> - </blockquote> - </example> - </sect3> - - <sect3> - <title>Tips, notes, warnings, cautions, important information and - sidebars.</title> - - <para>You may need to include extra information separate from the - main body of the text. Typically this is “meta” - information that the user should be aware of.</para> - - <para>Depending on the nature of the information, one of - <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, - <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and - <sgmltag>important</sgmltag> should be used. Alternatively, if the - information is related to the main text but is not one of the above, - use <sgmltag>sidebar</sgmltag>.</para> - - <para>The circumstances in which to choose one of these elements over - another is unclear. The DocBook documentation suggests;</para> - - <itemizedlist> - <listitem> - <para>A Note is for information that should be heeded by all - readers.</para> - </listitem> - - <listitem> - <para>An Important element is a variation on Note.</para> - </listitem> - - <listitem> - <para>A Caution is for information regarding possible data loss - or software damage.</para> - </listitem> - - <listitem> - <para>A Warning is for information regarding possible hardware - damage or injury to life or limb.</para> - </listitem> - </itemizedlist> - - <example> - <title><sgmltag>warning</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<warning> - <para>Installing FreeBSD may make you want to delete Windows from your - harddisk.</para> -</warning>]]></programlisting> - </example> - - <!-- Need to do this outside of the example --> - <warning> - <para>Installing FreeBSD may make you want to delete Windows from - your harddisk.</para> - </warning> - </sect3> - - <sect3> - <title>Lists and procedures</title> - - <para>You will often need to list pieces of information to the user, - or present them with a number of steps that must be carried out in - order to accomplish a particular goal.</para> - - <para>In order to do this, use <sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, or - <sgmltag>procedure</sgmltag><footnote><para>There are other types of - list element in DocBook, but we're not concerned with those at - the moment.</para> - </footnote> - </para> - - <para><sgmltag>itemizedlist</sgmltag> and - <sgmltag>orderedlist</sgmltag> are similar to the counterparts in - HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one - consists of one or more <sgmltag>listitem</sgmltag> elements, and - each <sgmltag>listitem</sgmltag> contains one or more block - elements. The <sgmltag>listitem</sgmltag> elements are analagous to - HTMLs <sgmltag>li</sgmltag> tags. However, unlike HTML they are - required.</para> - - <para><sgmltag>procedure</sgmltag> is slightly different. It consists - of <sgmltag>step</sgmltag>s, which may in turn consists of more - <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each - <sgmltag>step</sgmltag> contains block elements.</para> - - <example> - <title><sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, and - <sgmltag>procedure</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<itemizedlist> - <listitem> - <para>This is the first itemized item.</para> - </listitem> - - <listitem> - <para>This is the second itemized item.</para> - </listitem> -</itemizedlist> - -<orderedlist> - <listitem> - <para>This is the first ordered item.</para> - </listitem> - - <listitem> - <para>This is the second ordered item.</para> - </listitem> -</orderedlist>]]></programlisting> - - <para>Appearance:</para> - - <itemizedlist> - <listitem> - <para>This is the first itemized item.</para> - </listitem> - - <listitem> - <para>This is the second itemized item.</para> - </listitem> - </itemizedlist> - - <orderedlist> - <listitem> - <para>This is the first ordered item.</para> - </listitem> - - <listitem> - <para>This is the second ordered item.</para> - </listitem> - </orderedlist> - </example> - </sect3> - - <sect3> - <title>Showing file samples</title> - - <para>If you want to show a fragment of a file (or perhaps a complete - file) to the user, wrap it in the <sgmltag>programlisting</sgmltag> - element.</para> - - <para>White space and line breaks within - <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> - significant. In particular, this means that the closing tag should - appear on the same line as the last line of the output, otherwise a - spurious blank line will be included.</para> - - <example> - <title><sgmltag>programlisting</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA[<para>When you have finished, your program should look like - this;</para> - -<programlisting> -#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting>]]></programlisting> - - <para>Notice how the angle brackets in the - <literal>#include</literal> line need to be referenced by their - entities instead of being included literally.</para> - - <para>Appearance:</para> - - <para>When you have finished, your program should look like - this;</para> - - <programlisting> -#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting> - </example> - - <note> - <para>There is a mechanism within DocBook for referring to sections - of a previously occuring <sgmltag>programlisting</sgmltag>, called - callouts (see <sgmltag>programlistingco</sgmltag> for more - information). I don't fully understand (i.e., have never used) - this feature, so can't document it here. For the mean time, you - can include line numbers within the content, and then refer to - them later on in your description. That will change, as soon as I - find the time to understand and document callouts.</para> - </note> - </sect3> - - <sect3> - <title>Tables</title> - - <para>Unlike HTML, you do not need to use tables for layout purposes, - as the stylesheet handles those issues for you. Instead, just use - tables for marking up tabular data.</para> - - <para>In general terms (and see the DocBook documentation for more - detail) a table (which can be either formal or informal) consists of - a <sgmltag>table</sgmltag> element. This contains at least one - <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) - the number of columns in this table group. Within the tablegroup - you can then have one <sgmltag>thead</sgmltag> element, which - contains elements for the table headings (column headings), and one - <sgmltag>tbody</sgmltag> which contains the body of the - table.</para> - - <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag> - contain <sgmltag>row</sgmltag> elements, which in turn contain - <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag> - element specifies one cell in the table.</para> - - <example> - <title><sgmltag>informaltable</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>This is column head 1</entry> - <entry>This is column head 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Row 1, column 1</entry> - <entry>Row 1, column 2</entry> - </row> - - <row> - <entry>Row 2, column 1</entry> - <entry>Row 2, column 2</entry> - </row> - </tbody> - </tgroup> -</informaltable>]]></programlisting> - - <para>Appearance:</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>This is column head 1</entry> - <entry>This is column head 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Row 1, column 1</entry> - <entry>Row 1, column 2</entry> - </row> - - <row> - <entry>Row 2, column 1</entry> - <entry>Row 2, column 2</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </example> - - <para>If you don't want a border around the table the - <literal>frame</literal> attribute can be added to the - <sgmltag>informaltable</sgmltag> element with a value of - <literal>none</literal> (i.e., <literal><informaltable - frame="none"></literal>).</para> - - <example> - <title>Tables where <literal>frame="none"</literal></title> - - <para>Appearance:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>This is column head 1</entry> - <entry>This is column head 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Row 1, column 1</entry> - <entry>Row 1, column 2</entry> - </row> - - <row> - <entry>Row 2, column 1</entry> - <entry>Row 2, column 2</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </example> - </sect3> - - <sect3> - <title>Examples for the user to follow</title> - - <para>A lot of the time you need to show examples for the user to - follow. Typically, these will consist of dialogs with the computer; - the user types in a command, the user gets a response back, they - type in another command, and so on.</para> - - <para>A number of distinct elements and entities come in to play - here.</para> - - <variablelist> - <varlistentry> - <term><sgmltag>informalexample</sgmltag></term> - - <listitem> - <para>Most of the time these examples will occur - “mid-flow” as it were, and you won't need to put a - title on them. So, most of the time, the outermost element - will be <sgmltag>informalexample</sgmltag>. For those times - when you do need to include a title on the example, use - <sgmltag>example</sgmltag>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>screen</sgmltag></term> - - <listitem> - <para>Everything the user sees in this example will be on the - computer screen, so the next element is - <sgmltag>screen</sgmltag>.</para> - - <para>Within <sgmltag>screen</sgmltag>, white space is - significant.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>prompt</sgmltag>, - <literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal></term> - - <listitem> - <para>Some of the things the user will be seeing on the screen - are prompts from the computer (either from the OS, command - shell, or application. These should be marked up using - <sgmltag>prompt</sgmltag>.</para> - - <para>As a special case, the two shell prompts for the normal - user and the root user have been provided as entities. Every - time you want to indicate the user is at a shell prompt, use - one of <literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> as necessary. They do - not need to be inside <sgmltag>prompt</sgmltag>.</para> - - <note> - <para><literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> are FreeBSD - extensions to DocBook, and are not part of the original - DTD.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>userinput</sgmltag></term> - - <listitem> - <para>When displaying text that the user should type in, wrap it - in <sgmltag>userinput</sgmltag> tags. It will probably be - displayed differently to the user.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><sgmltag>informalexample</sgmltag>, - <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and - <sgmltag>userinput</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<informalexample> - <screen>&prompt.user; <userinput>ls -1</userinput> -foo1 -foo2 -foo3 -&prompt.user; <userinput>ls -1 | grep foo2</userinput> -foo2 -&prompt.user; <userinput>su</userinput> -<prompt>Password: </prompt> -&prompt.root; <userinput>cat foo2</userinput> -This is the file called 'foo2'</screen> -</informalexample>]]></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen>&prompt.user; <userinput>ls -1</userinput> -foo1 -foo2 -foo3 -&prompt.user; <userinput>ls -1 | grep foo2</userinput> -foo2 -&prompt.user; <userinput>su</userinput> -<prompt>Password: </prompt> -&prompt.root; <userinput>cat foo2</userinput> -This is the file called 'foo2'</screen> - </informalexample> - </example> - - <note> - <para>Even though we are displaying the contents of the file - <filename>foo2</filename>, it is <emphasis>not</emphasis> marked - up as <sgmltag>programlisting</sgmltag>. Reserve - <sgmltag>programlisting</sgmltag> for showing fragments of files - outside the context of user actions.</para> - </note> - </sect3> - </sect2> - - <sect2> - <title>In-line elements</title> - - <sect3> - <title>Emphasising information</title> - - <para>When you want to emphasise a particular word or phrase, use - <sgmltag>emphasis</sgmltag>. This may be presented as italic, or - bold, or might be spoken differently with a text-to-speech - system.</para> - - <para>There is no way to change the presentation of the emphasis - within your document, no equivalent of HTML's <sgmltag>b</sgmltag> - and <sgmltag>i</sgmltag>. If the information you are presenting is - important then consider presenting it in - <sgmltag>important</sgmltag> rather than - <sgmltag>emphasis</sgmltag>.</para> - - <example> - <title><sgmltag>emphasis</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> - premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix - like operating system for the Intel architecture.</para> - </example> - </sect3> - - <sect3> - <title>Applications, commands, options, and cites</title> - - <para>You will frequently want to refer to both applications and - commands when writing for the Handbook. The distinction between - them is simple; an application is the name for a suite (or possibly - just 1) of programs that fulfil a particular task. A command is the - name of a program that the user can run.</para> - - <para>In addition, you will occasionally need to list one or more of - the options that a command might take.</para> - - <para>Finally, you will often want to list a command with it's manual - section number, in the “command(number)” format so - common in Unix manuals.</para> - - <para>Mark up application names with - <sgmltag>application</sgmltag>.</para> - - <para>When you want to list a command with it's manual section number - (which should be most of the time) the DocBook element is - <sgmltag>citerefentry</sgmltag>. This will contain a further two - elements, <sgmltag>refentrytitle</sgmltag> and - <sgmltag>manvolnum</sgmltag>. The content of - <sgmltag>refentrytitle</sgmltag> is the name of the command, and the - content of <sgmltag>manvolnum</sgmltag> is the manual page - section.</para> - - <para>This can be cumbersome to write, and so a series of <link - linkend="sgml-primer-general-entities">general entities</link> - have been created to make this easier. Each entity takes the form - <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> - - <para>The file that contains these entities is in - <filename>doc/share/sgml/man-refs.ent</filename>, and can be - referred to using this FPI;</para> - - <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> - - <para>Therefore, the introduction to your documentation will probably - look like this;</para> - - <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -… - -]]></programlisting> - - <para>Use <sgmltag>command</sgmltag> when you want to include a - command name “in-line” but present it as something the - user should type in.</para> - - <para>Use <sgmltag>option</sgmltag> to mark up a command's - options.</para> - - <para>This can be confusing, and sometimes the choice is not always - clear. Hopefully this example makes it clearer.</para> - - <example> - <title>Applications, commands, and options.</title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para><application>Sendmail</application> is the most - widely used Unix mail application.</para> - -<para><application>Sendmail</application> includes the - <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, &man.sendmail.8;, and &man.newaliases.8; - programs.</para> - -<para>One of the command line parameters to <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, <option>-bp</option>, will display the current - status of messages in the mail queue. Check this on the command - line by running <command>sendmail -bp</command>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para><application>Sendmail</application> is the most widely used - Unix mail application.</para> - - <para><application>Sendmail</application> includes the - <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, <citerefentry> - <refentrytitle>mailq</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, and <citerefentry> - <refentrytitle>newaliases</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry> programs.</para> - - <para>One of the command line parameters to <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, <option>-bp</option>, will display the current - status of messages in the mail queue. Check this on the command - line by running <command>sendmail -bp</command>.</para> - </example> - - <note> - <para>Notice how the - <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para> - </note> - </sect3> - - <sect3> - <title>Files, directories, extensions</title> - - <para>Whenever you wish to refer to the name of a file, a directory, - or a file extension, use <sgmltag>filename</sgmltag>.</para> - - <example> - <title><sgmltag>filename</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>The SGML source for the Handbook in English can be - found in <filename>/usr/doc/en/handbook/</filename>. The first - file is called <filename>handbook.sgml</filename> in that - directory. You should also see a <filename>Makefile</filename> - and a number of files with a <filename>.ent</filename> - extension.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The SGML source for the Handbook in English can be found in - <filename>/usr/doc/en/handbook/</filename>. The first file is - called <filename>handbook.sgml</filename> in that directory. You - should also see a <filename>Makefile</filename> and a number of - files with a <filename>.ent</filename> extension.</para> - </example> - </sect3> - - <sect3> - <title>Devices</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>When referring to devices you have two choices. You can either - refer to the device as it appears in <filename>/dev</filename>, or - you can use the name of the device as it appears in the kernel. For - this latter course, use <sgmltag>devicename</sgmltag>.</para> - - <para>Sometimes you will not have a choice. Some devices, such as - networking cards, do not have entries in <filename>/dev</filename>, - or the entries are markedly different from those entries.</para> - - <example> - <title><sgmltag>devicename</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para><devicename>sio</devicename> is used for serial - communication in FreeBSD. <devicename>sio</devicename> manifests - through a number of entries in <filename>/dev</filename>, including - <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> - -<para>By contrast, the networking devices, such as - <devicename>ed0</devicename> do not appear in <filename>/dev</filename>. - -<para>In MS-DOS, the first floppy drive is referred to as - <devicename>a:</devicename>. In FreeBSD it is - <filename>/dev/fd0</filename>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para><devicename>sio</devicename> is used for serial communication - in FreeBSD. <devicename>sio</devicename> manifests through a - number of entries in <filename>/dev</filename>, including - <filename>/dev/ttyd0</filename> and - <filename>/dev/cuaa0</filename>.</para> - - <para>By contrast, the networking devices, such as - <devicename>ed0</devicename> do not appear in - <filename>/dev</filename>.</para> - - <para>In MS-DOS, the first floppy drive is referred to as - <devicename>a:</devicename>. In FreeBSD it is - <filename>/dev/fd0</filename>.</para> - </example> - </sect3> - - <sect3> - <title>Hosts, domains, IP addresses, and so forth</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>You can markup identification information for networked - computers (hosts) in several ways, depending on the nature of the - information. All of them use <sgmltag>hostid</sgmltag> as the - element, with the <literal>role</literal> attribute selecting the - type of the marked up information.</para> - - <variablelist> - <varlistentry> - <term>No role attribute, or - <literal>role="hostname"</literal></term> - - <listitem> - <para>With no role attribute (i.e., - <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the - marked up information is the simple hostname, such as - <literal>freefall</literal> or <literal>wcarchive</literal>. - You can explicitly specify this with - <literal>role="hostname"</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="domainname"</literal></term> - - <listitem> - <para>The text is a domain name, such as - <literal>freebsd.org</literal> or - <literal>ngo.org.uk</literal>. There is no hostname - component.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="fqdn"</literal></term> - - <listitem> - <para>The text is a Fully Qualified Domain Name, with both - hostname and domain name parts.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="ipaddr"</literal></term> - - <listitem> - <para>The text is an IP address, probably expressed as a dotted - quad.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="netmask"</literal></term> - - <listitem> - <para>The text is a network mask, which might be expressed as a - dotted quad, a hexadecimal string, or as a - <literal>/</literal> followed by a number.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="mac"</literal></term> - - <listitem> - <para>The text is an ethernet MAC address, expressed as a series - of 2 digit hexadecimal numbers seperated by colons.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><sgmltag>hostid</sgmltag> and roles</title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>The local machine can always be referred to by the - name <hostid>localhost</hostid>, which will have the IP address - <hostid role="ipaddr">127.0.0.1</hostid>.</para> - -<para>The <hostid role="domainname">freebsd.org</hostid> domain - contains a number of different hosts, including - <hostid role="fqdn">freefall.freebsd.org</hostid> and - <hostid role="fqdn">bento.freebsd.org</hostid>.</para> - -<para>When adding an IP alias to an interface (using - <command>ifconfig</command>) <emphasis>always</emphasis> use a - netmask of <hostid role="netmask">255.255.255.255</hostid> - (which can also be expressed as <hostid - role="netmask">0xffffffff</hostid>.</para> - -<para>The MAC address uniquely identifies every network card in - in existence. A typical MAC address looks like <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The local machine can always be referred to by the name - <hostid>localhost</hostid>, which will have the IP address <hostid - role="ipaddr">127.0.0.1</hostid>.</para> - - <para>The <hostid role="domainname">freebsd.org</hostid> domain - contains a number of different hosts, including <hostid - role="fqdn">freefall.freebsd.org</hostid> and <hostid - role="fqdn">bento.freebsd.org</hostid>.</para> - - <para>When adding an IP alias to an interface (using - <command>ifconfig</command>) <emphasis>always</emphasis> use a - netmask of <hostid role="netmask">255.255.255.255</hostid> (which - can also be expressed as <hostid - role="netmask">0xffffffff</hostid>.</para> - - <para>The MAC address uniquely identifies every network card in - existence. A typical MAC address looks like <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para> - </example> - </sect3> - - <sect3> - <title>Usernames</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>When you need to refer to a specific username, such as - <literal>root</literal> or <literal>bin</literal>, use - <sgmltag>username</sgmltag>.</para> - - <example> - <title><sgmltag>username</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>To carry out most system administration functions you - will need to be <username>root</username>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>To carry out most system administration functions you will - need to be <username>root</username>.</para> - </example> - </sect3> - - <sect3> - <title>Describing <filename>Makefile</filename>s</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>Two elements exist to describe parts of - <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag>.</para> - - <para><sgmltag>maketarget</sgmltag> identifies a build target exported - by a <filename>Makefile</filename> that can be given as a parameter - to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a - variable that can be set (in the environment, on the - <command>make</command> command line, or within the - <filename>Makefile</filename>) to influence the process.</para> - - <example> - <title><sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>Two common targets in a <filename>Makefile</filename> - are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para> - -<para>Typically, invoking <maketarget>all</maketarget> will rebuild the - application, and invoking <maketarget>clean</maketarget> will remove - the temporary files (<filename>.o</filename> for example) created by - the build process.</para> - -<para><maketarget>clean</maketarget> may be controlled by a number of - variables, including <makevar>CLOBBER</makevar> and - <makevar>RECURSE</makevar>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>Two common targets in a <filename>Makefile</filename> are - <maketarget>all</maketarget> and - <maketarget>clean</maketarget>.</para> - - <para>Typically, invoking <maketarget>all</maketarget> will rebuild - the application, and invoking <maketarget>clean</maketarget> will - remove the temporary files (<filename>.o</filename> for example) - created by the build process.</para> - - <para><maketarget>clean</maketarget> may be controlled by a number - of variables, including <makevar>CLOBBER</makevar> and - <makevar>RECURSE</makevar>.</para> - </example> - </sect3> - - <sect3> - <title>Literal text</title> - - <para>You will often need to include “literal” text in the - Handbook. This is text that is excerpted from another file, or - which should be copied from the Handbook into another file - verbatim.</para> - - <para>Some of the time, <sgmltag>programlisting</sgmltag> will be - sufficient to denote this text. <sgmltag>programlisting</sgmltag> - is not always appropriate, particularly when you want to include a - portion of a file “in-line” with the rest of the - paragraph.</para> - - <para>On these occasions, use <sgmltag>literal</sgmltag>.</para> - - <example> - <title><sgmltag>literal</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel - configuration file determines the size of many system tables, and is - a rough guide to how many simultaneous logins the system will - support.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The <literal>maxusers 10</literal> line in the kernel - configuration file determines the size of many system tables, and - is a rough guide to how many simultaneous logins the system will - support.</para> - </example> - </sect3> - - <sect3> - <title>Showing items that the user <emphasis>must</emphasis> fill - in</title> - - <para>There will often be times when you want to show the user what to - do, or refer to a file, or command line, or similar, where the user - can not simply copy the examples that you provide, but must instead - include some information themselves.</para> - - <para><sgmltag>replaceable</sgmltag> is designed for this eventuality. - Use it <emphasis>inside</emphasis> other elements to indicate parts - of that element's content that the user must replace.</para> - - <example> - <title><sgmltag>replaceable</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> -</informalexample>]]></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - </informalexample> - - <para><sgmltag>replaceable</sgmltag> can be used in many different - elements, including <sgmltag>literal</sgmltag>. This example also - shows that <sgmltag>replaceable</sgmltag> should only be wrapped - around the content that the user <emphasis>is</emphasis> meant to - provide. The other content should be left alone.</para> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal> - line in the kernel configuration file determines the size of many system - tables, and is a rough guide to how many simultaneous logins the system will - support.</para> - -<para>For a desktop workstation, <literal>32</literal> is a good value - for <replaceable>n</replaceable>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The <literal>maxusers <replaceable>n</replaceable></literal> - line in the kernel configuration file determines the size of many - system tables, and is a rough guide to how many simultaneous - logins the system will support.</para> - - <para>For a desktop workstation, <literal>32</literal> is a good - value for <replaceable>n</replaceable>.</para> - </example> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also in-line elements.</para> - </note> - - <sect3> - <title>Linking to other parts of the same document</title> - - <para>Linking within the same document requires you to to specify - where you are linking from (i.e., the text the user will click, or - otherwise indicate, as the source of the link) and where you are - linking to (the link's destination).</para> - - <para>Each element within DocBook has an attribute called - <literal>id</literal>. You can place text in this attribute to - uniquely name the element it is attached to.</para> - - <para>This value will be used when you specify the link - source.</para> - - <para>Normally, you will only be linking to chapters or sections, so - you would add the <literal>id</literal> attribute to these - elements.</para> - - <example> - <title><literal>id on chapters and sections</literal></title> - - <programlisting> -<![ CDATA [<chapter id="chapter1"> - <title>Introduction</title> - - <para>This is the introduction. It contains a subsection, - which is identified as well.</para> - - <sect1 id="chapter1-sect1"> - <title>Sub-sect 1</title> - - <para>This is the subsection.</para> - </sect1> -</chapter>]]></programlisting> - </example> - - <para>Obviously, you should use more descriptive values. The values - must be unique within the document (i.e., not just the file, but the - document the file might be included in as well). Notice how the - <literal>id</literal> for the subsection is constructed by appending - text to the <literal>id</literal> of the chapter. This helps to - ensure that they are unique.</para> - - <para>If you want to allow the user to jump into a specific portion of - the document (possibly in the middle of a paragraph or an example), - use <sgmltag>anchor</sgmltag>. This element has no content, but - takes an <literal>id</literal> attribute.</para> - - <example> - <title><sgmltag>anchor</sgmltag></title> - - <programlisting> -<![ CDATA [<para>This paragraph has an embedded - <anchor id="para1">link target in it. It won't show up in - the document.</para>]]></programlisting> - </example> - - <para>When you want to provide the user with a link they can activate - (probably by clicking) to go to a section of the document that has - an <literal>id</literal> attribute, you can use either - <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para> - - <para>Both of these elements have a <literal>linkend</literal> - attribute. The value of this attribute should be the value that you - have used in a <literal>id</literal> attribute (it does not matter - if that value has not yet occured in your document, this will work - for forward links as well as backward links).</para> - - <para>If you use <sgmltag>xref</sgmltag> then you have no control over - the text of the link. It will be generated for you.</para> - - <example> - <title>Using <sgmltag>xref</sgmltag></title> - - <para>Assume that this fragment appears somewhere in a document that - includes the <literal>id</literal> example;</para> - - <programlisting> -<![ CDATA [<para>More information can be found - in <xref linkend="chapter1">.</para> - -<para>More specific information can be found - in <xref linkend="chapter1-sect1">.</para>]]></programlisting> - - <para>The text of the link will be generated automatically, and will - look like (<emphasis>emphasised</emphasis> text indicates the text - that will be the link);</para> - - <blockquote> - <para>More information can be found in <emphasis>Chapter - One</emphasis>.</para> - - <para>More specific information can be found in <emphasis>the - section called Sub-sect 1</emphasis>.</para> - </blockquote> - </example> - - <para>Notice how the text from the link is derived from the section - title or the chapter number.</para> - - <note> - <para>This means that you <emphasis>can not</emphasis> use - <sgmltag>xref</sgmltag> to link to an <literal>id</literal> - attribute on an <sgmltag>anchor</sgmltag> element. The - <sgmltag>anchor</sgmltag> has no content, so the - <sgmltag>xref</sgmltag> can not generate the text for the - link.</para> - </note> - - <para>If you want to control the text of the link then use - <sgmltag>link</sgmltag>. This element wraps content, and the - content will be used for the link.</para> - - <example> - <title>Using <sgmltag>link</sgmltag></title> - - <para>Assume that this fragment appears somewhere in a document that - includes the <literal>id</literal> example.</para> - - <programlisting> -<![ CDATA [<para>More information can be found in - <link linkend="chapter1">the first chapter</link>.</para> - -<para>More specific information can be found in - <link linkend="chapter1-sect1>this</link> section.</para>]]></programlisting> - - <para>This will generate the following - (<emphasis>emphasised</emphasis> text indicates the text that will - be the link);</para> - - <blockquote> - <para>More information can be found in <emphasis>the first - chapter</emphasis>.</para> - - <para>More specific information can be found in - <emphasis>this</emphasis> section.</para> - </blockquote> - </example> - - <note> - <para>That last one is a bad example. Never use words like - “this” or “here” as the source for the - link. The reader will need to hunt around the surrounding context - to see where the link is actually taking them.</para> - </note> - - <note> - <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to - include a link to an <literal>id</literal> on an - <sgmltag>anchor</sgmltag> element, since the - <sgmltag>link</sgmltag> content defines the text that will be used - for the link.</para> - </note> - </sect3> - - <sect3> - <title>Linking to documents on the WWW</title> - - <para>Linking to external documents is much simpler, as long as you - know the URL of the document you want to link to. Use - <sgmltag>ulink</sgmltag>. The <literal>url</literal> attribute is - the URL of the page that the link points to, and the content of the - element is the text that will be displayed for the user to - activate.</para> - - <example> - <title><sgmltag>ulink</sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<para>Of course, you could stop reading this document and - go to the <ulink url="http://www.freebsd.org/">FreeBSD - home page</ulink> instead.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>Of course, you could stop reading this document and go to the - <ulink url="http://www.freebsd.org/">FreeBSD home page</ulink> - instead.</para> - </example> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>* LinuxDoc</title> - - <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the - <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation - Project</ulink>, and subsequently adopted by the FreeBSD Documentation - Project.</para> - - <para>The LinuxDoc DTD contains primarily appearance related markup rather - than content related markup (i.e., it describes what something looks - like rather than what it is).</para> - - <para>Both the FreeBSD Documentation Project and the Linux Documentation - Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para> - - <para>The LinuxDoc DTD is available from the ports collection in the - <filename>textproc/linuxdoc</filename> category.</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: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en/tutorials/docproj-primer/sgml-primer/chapter.sgml b/en/tutorials/docproj-primer/sgml-primer/chapter.sgml deleted file mode 100644 index c3b2c4d80e..0000000000 --- a/en/tutorials/docproj-primer/sgml-primer/chapter.sgml +++ /dev/null @@ -1,1589 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.7 1999-07-30 21:25:50 nik Exp $ ---> - -<chapter id="sgml-primer"> - <title>SGML Primer</title> - - <para>The majority of FDP documentation is written in applications of - SGML. This chapter explains exactly what that means, how to read - and understand the source to the documentation, and the sort of SGML - tricks you will see used in the documentation.</para> - - <para>Portions of this section were inspired by Mark Galassi's <ulink - url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para> - - <sect1> - <title>Overview</title> - - <para>Way back when, electronic text was simple to deal with. Admittedly, - you had to know which character set your document was written in (ASCII, - EBCDIC, or one of a number of others) but that was about it. Text was - text, and what you saw really was what you got. No frills, no - formatting, no intelligence.</para> - - <para>Inevitably, this was not enough. Once you have text in a - machine-usable format, you expect machines to be able to use it and - manipulate it intelligently. You would like to indicate that certain - phrases should be emphasised, or added to a glossary, or be hyperlinks. - You might want filenames to be shown in a “typewriter” style - font for viewing on screen, but as “italics” when printed, - or any of a myriad of other options for presentation.</para> - - <para>It was once hoped that Artificial Intelligence (AI) would make this - easy. Your computer would read in the document and automatically - identify key phrases, filenames, text that the reader should type in, - examples, and more. Unfortunately, real life has not happened quite - like that, and our computers require some assistance before they can - meaningfully process our text.</para> - - <para>More precisely, they need help identifying what is what. You or I - can look at - - <blockquote> - <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> - - <screen>&prompt.user; <command>rm /tmp/foo</command></screen> - </blockquote> - - and easily see which parts are filenames, which are commands to be typed - in, which parts are references to manual pages, and so on. But the - computer processing the document can not. For this we need - markup.</para> - - <para>“Markup” is commonly used to describe “adding - value” or “increasing cost”. The term takes on both - these meanings when applied to text. Markup is additional text included - in the document, distinguished from the document's content in some way, - so that programs that process the document can read the markup and use - it when making decisions about the document. Editors can hide the - markup from the user, so the user is not distracted by it.</para> - - <para>The extra information stored in the markup <emphasis>adds - value</emphasis> to the document. Adding the markup to the document - must typically be done by a person—after all, if computers could - recognise the text sufficiently well to add the markup then there would - be no need to add it in the first place. This <emphasis>increases the - cost</emphasis> of the document.</para> - - <para>The previous example is actually represented in this document like - this;</para> - - <programlisting><![ CDATA [ -<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> - -<para><command>rm /tmp/foo</command></para>]]></programlisting> - - <para>As you can see, the markup is clearly separate from the - content.</para> - - <para>Obviously, if you are going to use markup you need to define what - your markup means, and how it should be interpreted. You will need a - markup language that you can follow when marking up your - documents.</para> - - <para>Of course, one markup language might not be enough. A markup - language for technical documentation has very different requirements - than a markup language that was to be used for cookery recipes. This, - in turn, would be very different from a markup language used to describe - poetry. What you really need is a first language that you use to write - these other markup languages. A <emphasis>meta markup - language</emphasis>.</para> - - <para>This is exactly what the Standard Generalised Markup Language (SGML) - is. Many markup languages have been written in SGML, including the two - most used by the FDP, HTML and DocBook.</para> - - <para>Each language definition is more properly called a Document Type - Definition (DTD). The DTD specifies the name of the elements that can - be used, what order they appear in (and whether some markup can be used - inside other markup) and related information. A DTD is sometimes - referred to as an <emphasis>application</emphasis> of SGML.</para> - - <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis> - specification of all the elements that are allowed to appear, the order - in which they should appear, which elements are mandatory, which are - optional, and so forth. This makes it possible to write an SGML - <emphasis>parser</emphasis> which reads in both the DTD and a document - which claims to conform to the DTD. The parser can then confirm whether - or not all the elements required by the DTD are in the document in the - right order, and whether there are any errors in the markup. This is - normally referred to as <quote>validating the document</quote>.</para> - - <note> - <para>This processing simply confirms that the choice of elements, their - ordering, and so on, conforms to that listed in the DTD. It does - <emphasis>not</emphasis> check that you have used - <emphasis>appropriate</emphasis> markup for the content. If you were - to try and mark up all the filenames in your document as function - names, the parser would not flag this as an error (assuming, of - course, that your DTD defines elements for filenames and functions, - and that they are allowed to appear in the same place).</para> - </note> - - <para>It is likely that most of your contributions to the Documentation - Project will consist of content marked up in either HTML or DocBook, - rather than alterations to the DTDs. For this reason this book will - not touch on how to write a DTD.</para> - </sect1> - - <sect1 id="sgml-primer-elements"> - <title>Elements, tags, and attributes</title> - - <para>All the DTDs written in SGML share certain characteristics. This is - hardly surprising, as the philosophy behind SGML will inevitably show - through. One of the most obvious manifestations of this philisophy is - that of <emphasis>content</emphasis> and - <emphasis>elements</emphasis>.</para> - - <para>Your documentation (whether it is a single web page, or a lengthy - book) is considered to consist of content. This content is then divided - (and further subdivided) into elements. The purpose of adding markup is - to name and identify the boundaries of these elements for further - processing.</para> - - <para>For example, consider a typical book. At the very top level, the - book is itself an element. This “book” element obviously - contains chapters, which can be considered to be elements in their own - right. Each chapter will contain more elements, such as paragraphs, - quotations, and footnotes. Each paragraph might contain further - elements, identifying content that was direct speech, or the name of a - character in the story.</para> - - <para>You might like to think of this as “chunking” content. - At the very top level you have one chunk, the book. Look a little - deeper, and you have more chunks, the individual chapters. These are - chunked further into paragraphs, footnotes, character names, and so - on.</para> - - <para>Notice how you can make this differentation between different - elements of the content without resorting to any SGML terms. It really - is surprisingly straightforward. You could do this with a highlighter - pen and a printout of the book, using different colours to indicate - different chunks of content.</para> - - <para>Of course, we do not have an electronic highlighter pen, so we need - some other way of indicating which element each piece of content belongs - to. In languages written in SGML (HTML, DocBook, et al) this is done by - means of <emphasis>tags</emphasis>.</para> - - <para>A tag is used to identify where a particular element starts, and - where the element ends. <emphasis>The tag is not part of the element - itself</emphasis>. Because each DTD was normally written to mark up - specific types of information, each one will recognise different - elements, and will therefore have different names for the tags.</para> - - <para>For an element called <replaceable>element-name</replaceable> the - start tag will normally look like - <literal><<replaceable>element-name</replaceable>></literal>. The - corresponding closing tag for this element is - <literal></<replaceable>element-name</replaceable>></literal>.</para> - - <example> - <title>Using an element (start and end tags)</title> - - <para>HTML has an element for indicating that the content enclosed by - the element is a paragraph, called <literal>p</literal>. This - element has both start and end tags.</para> - - <programlisting> -<![ CDATA [<p>This is a paragraph. It starts with the start tag for - the 'p' element, and it will end with the end tag for the 'p' - element.</p> - -<p>This is another paragraph. But this one is much shorter.</p>]]></programlisting> - </example> - - <para>Not all elements require an end tag. Some elements have no content. - For example, in HTML you can indicate that you want a horizontal line to - appear in the document. Obviously, this line has no content, so just - the start tag is required for this element.</para> - - <example> - <title>Using an element (start tag only)</title> - - <para>HTML has an element for indicating a horizontal rule, called - <literal>hr</literal>. This element does not wrap content, so only - has a start tag.</para> - - <programlisting> -<![ CDATA [<p>This is a paragraph.</p> - -<hr> - -<p>This is another paragraph. A horizontal rule separates this - from the previous paragraph.</p>]]></programlisting> - </example> - - <para>If it is not obvious by now, elements can contain other elements. - In the book example earlier, the book element contained all the chapter - elements, which in turn contained all the paragraph elements, and so - on.</para> - - <example> - <title>Elements within elements; <sgmltag>em</sgmltag></title> - - <programlisting> -<![ CDATA [<p>This is a simple <em>paragraph</em> where some - of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting> - </example> - - <para>The DTD will specify the rules detailing which elements can contain - other elements, and exactly what they can contain.</para> - - <important> - <para>People often confuse the terms tags and elements, and use the - terms as if they were interchangeable. They are not.</para> - - <para>An element is a conceptual part of your document. An element has - a defined start and end. The tags mark where the element starts and - end.</para> - - <para>When this document (or anyone else knowledgable about SGML) refers - to “the <p> tag” they mean the literal text - consisting of the three characters <literal><</literal>, - <literal>p</literal>, and <literal>></literal>. But the phrase - “the <p> element” refers to the whole - element.</para> - - <para>This distinction <emphasis>is</emphasis> very subtle. But keep it - in mind.</para> - </important> - - <para>Elements can have attributes. An attribute has a name and a value, - and is used for adding extra information to the element. This might be - information that indicates how the content should be rendered, or might - be something that uniquely identifies that occurence of the element, or - it might be something else.</para> - - <para>An element's attributes are written <emphasis>inside</emphasis> the - start tag for that element, and take the form - <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> - - <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag> - element has an attribute called <literal>align</literal>, which suggests - an alignment (justification) for the paragraph to the program displaying - the HTML.</para> - - <para>The <literal>align</literal> attribute can take one of four defined - values, <literal>left</literal>, <literal>center</literal>, - <literal>right</literal> and <literal>justify</literal>. If the - attribute is not specified then the default is - <literal>left</literal>.</para> - - <example> - <title>Using an element with an attribute</title> - - <programlisting> -<![ CDATA [<p align="left">The inclusion of the align attribute - on this paragraph was superfluous, since the default is left.</p> - -<p align="center">This may appear in the center.</p>]]></programlisting> - </example> - - <para>Some attributes will only take specific values, such as - <literal>left</literal> or <literal>justify</literal>. Others will - allow you to enter anything you want. If you need to include quotes - (<literal>"</literal>) within an attribute then use single quotes around - the attribute value.</para> - - <example> - <title>Single quotes around attributes</title> - - <programlisting> -<![ CDATA [<p align='right'>I'm on the right!</p>]]></programlisting> - </example> - - <para>Sometimes you do not need to use quotes around attribute values at - all. However, the rules for doing this are subtle, and it is far - simpler just to <emphasis>always</emphasis> quote your attribute - values.</para> - - <sect2> - <title>For you to do…</title> - - <para>In order to run the examples in this document you will need to - install some software on your system and ensure that an environment - variable is set correctly.</para> - - <procedure> - <step> - <para>Download and install <filename>textproc/docproj</filename> - from the FreeBSD ports system. This is a - <emphasis>meta-port</emphasis> that should download and install - all of the programs and supporting files that are used by the - Documentation Project.</para> - </step> - - <step> - <para>Add lines to your shell startup files to set - <envar>SGML_CATALOG_FILES</envar>.</para> - - <example id="sgml-primer-envars"> - <title><filename>.profile</filename>, for &man.sh.1; and - &man.bash.1; users</title> - - <programlisting> -SGML_ROOT=/usr/local/share/sgml -SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog -SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES -export SGML_CATALOG_FILES</programlisting> - </example> - - <example> - <title><filename>.login</filename>, for &man.csh.1; and - &man.tcsh.1; users</title> - - <programlisting> -setenv SGML_ROOT /usr/local/share/sgml -setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog -setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES</programlisting> - </example> - - <para>Then either log out, and log back in again, or run those - commands from the command line to set the variable values.</para> - </step> - </procedure> - - <procedure> - <step> - <para>Create <filename>example.sgml</filename>, and enter the - following text;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>This is a paragraph containing some text.</p> - - <p>This paragraph contains some more text.</p> - - <p align="right">This paragraph might be right-justified.</p> - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Try and validate this file using an SGML parser.</para> - - <para>Part of <filename>textproc/docproj</filename> is the - &man.nsgmls.1; <link linkend="sgml-primer-validating">validating - parser</link>. Normally, &man.nsgmls.1; reads in a document - marked up according to an SGML DTD and returns a copy of the - document's Element Structure Information Set (ESIS, but that is - not important right now).</para> - - <para>However, when <option>-s</option> is passed as a parameter to - it, &man.nsgmls.1; will suppress its normal output, and just print - error messages. This makes it a useful way to check to see if your - document is valid or not.</para> - - <para>Use &man.nsgmls.1; to check that your document is - valid;</para> - - <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen> - - <para>As you will see, &man.nsgmls.1; returns without displaying any - output. This means that your document validated - successfully.</para> - </step> - - <step> - <para>See what happens when required elements are omitted. Try - removing the <sgmltag>title</sgmltag> and - <sgmltag>/title</sgmltag> tags, and re-run the validation.</para> - - <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> -nsgmls:example.sgml:5:4:E: character data is not allowed here -nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> - - <para>The error output from &man.nsgmls.1; is organised into - colon-separated groups, or columns.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Column</entry> - <entry>Meaning</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>The name of the program generating the error. This - will always be <literal>nsgmls</literal>.</entry> - </row> - - <row> - <entry>2</entry> - <entry>The name of the file that contains the error.</entry> - </row> - - <row> - <entry>3</entry> - <entry>Line number where the error appears.</entry> - </row> - - <row> - <entry>4</entry> - <entry>Column number where the error appears.</entry> - </row> - - <row> - <entry>5</entry> - <entry>A one letter code indicating the nature of the - message. <literal>I</literal> indicates an informational - message, <literal>W</literal> is for warnings, and - <literal>E</literal> is for errors<footnote> - <para>It is not always the fifth column either. - <command>nsgmls -sv</command> displays - <literal>nsgmls:I: SP version "1.3"</literal> - (depending on the installed version). As you can see, - this is an informational message.</para> - </footnote>, and <literal>X</literal> is for - cross-references. As you can see, these messages are - errors.</entry> - </row> - - <row> - <entry>6</entry> - <entry>The text of the error message.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para><ulink - url="http://www.cs.duke.edu/~dsb/kgv-faq/errors.html">More - information about errors from &man.nsgmls.1;</ulink> is - available in the <ulink - url="http://www.cs.duke.edu/~dsb/kgv-faq/">Unofficial 'Kindler, - Gentler HTML Validator' FAQ</ulink>.</para> - - <para>Simply omitting the <sgmltag>title</sgmltag> tags has - generated 2 different errors.</para> - - <para>The first error indicates that content (in this case, - characters, rather than the start tag for an element) has occured - where the SGML parser was expecting something else. In this case, - the parser was expecting to see one of the start tags for elements - that are valid inside <sgmltag>head</sgmltag> (such as - <sgmltag>title</sgmltag>).</para> - - <para>The second error is because <sgmltag>head</sgmltag> elements - <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag> - element. Because it does not &man.nsgmls.1; considers that the - element has not been properly finished. However, the closing tag - indicates that the element has been closed before it has been - finished.</para> - </step> - - <step> - <para>Put the <literal>title</literal> element back in.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 id="sgml-primer-doctype-declaration"> - <title>The DOCTYPE declaration</title> - - <para>The beginning of each document that you write must specify the name - of the DTD that the document conforms to. This is so that SGML parsers - can determine the DTD and ensure that the document does conform to - it.</para> - - <para>This information is generally expressed on one line, in the DOCTYPE - declaration.</para> - - <para>A typical declaration for a document written to conform with version - 4.0 of the HTML DTD looks like this;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> - - <para>That line contains a number of different components.</para> - - <variablelist> - <varlistentry> - <term><literal><!</literal></term> - - <listitem> - <para>Is the <emphasis>indicator</emphasis> that indicates that this - is an SGML declaration. This line is declaring the document type. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>DOCTYPE</literal></term> - - <listitem> - <para>Shows that this is an SGML declaration for the document - type.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>html</literal></term> - - <listitem> - <para>Names the first <link linkend="sgml-primer-elements">element</link> that - will appear in the document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term> - - <listitem> - <para>Lists the Formal Public Identifier (FPI) for the DTD that this - document conforms to. Your SGML parser will use this to find the - correct DTD when processing this document.</para> - - <para><literal>PUBLIC</literal> is not a part of the FPI, but - indicates to the SGML processor how to find the DTD referenced in - the FPI. Other ways of telling the SGML parser how to find the - DTD are shown <link - linkend="sgml-primer-fpi-alternatives">later</link>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>></literal></term> - - <listitem> - <para>Returns to the document.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Formal Public Identifiers (FPIs)</title> - - <note> - <para>You don't need to know this, but it's useful background, and - might help you debug problems when your SGML processor can't locate - the DTD you are using.</para> - </note> - - <para>FPIs must follow a specific syntax. This syntax is as - follows;</para> - - <programlisting> -"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> - - <variablelist> - <varlistentry> - <term><replaceable>Owner</replaceable></term> - - <listitem> - <para>This indicates the owner of the FPI.</para> - - <para>If this string starts with “ISO” then this is an - ISO owned FPI. For example, the FPI <literal>"ISO - 8879:1986//ENTITIES Greek Symbols//EN"</literal> lists - <literal>ISO 8879:1986</literal> as being the owner for the set - of entities for greek symbols. ISO 8879:1986 is the ISO number - for the SGML standard.</para> - - <para>Otherwise, this string will either look like - <literal>-//<replaceable>Owner</replaceable></literal> or - <literal>+//<replaceable>Owner</replaceable></literal> (notice - the only difference is the leading <literal>+</literal> or - <literal>-</literal>).</para> - - <para>If the string starts with <literal>-</literal> then the - owner information is unregistered, with a <literal>+</literal> - it identifies it as being registered.</para> - - <para>ISO 9070:1991 defines how registered names are generated; it - might be derived from the number of an ISO publication, an ISBN - code, or an organisation code assigned according to ISO 6523. - In addition, a registration authority could be created in order - to assign registered names. The ISO council delegated this to - the American National Standards Institute (ANSI).</para> - - <para>Because the FreeBSD Project hasn't been registered the - owner string is <literal>-//FreeBSD</literal>. And as you can - see, the W3C are not a registered owner either.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Keyword</replaceable></term> - - <listitem> - <para>There are several keywords that indicate the type of - information in the file. Some of the most common keywords are - <literal>DTD</literal>, <literal>ELEMENT</literal>, - <literal>ENTITIES</literal>, and <literal>TEXT</literal>. - <literal>DTD</literal> is used only for DTD files, - <literal>ELEMENT</literal> is usually used for DTD fragments - that contain only entity or element declarations. - <literal>TEXT</literal> is used for SGML content (text and - tags).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Description</replaceable></term> - - <listitem> - <para>Any description you want to supply for the contents of this - file. This may include version numbers or any short text that - is meaningful to you and unique for the SGML system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Language</replaceable></term> - - <listitem> - <para>This is an ISO two-character code that identifies the native - language for the file. <literal>EN</literal> is used for - English.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect3> - <title><filename>catalog</filename> files</title> - - <para>If you use the syntax above and try and process this document - using an SGML processor, the processor will need to have some way of - turning the FPI into the name of the file on your computer that - contains the DTD.</para> - - <para>In order to do this it can use a catalog file. A catalog file - (typically called <filename>catalog</filename>) contains lines that - map FPIs to filenames. For example, if the catalog file contained - the line;</para> - - <programlisting> -PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> - - <para>The SGML processor would know to look up the DTD from - <filename>strict.dtd</filename> in the <filename>4.0</filename> - subdirectory of whichever directory held the - <filename>catalog</filename> file that contained that line.</para> - - <para>Look at the contents of - <filename>/usr/local/share/sgml/html/catalog</filename>. This is - the catalog file for the HTML DTDs that will have been installed as - part of the <filename>textproc/docproj</filename> port.</para> - </sect3> - - <sect3> - <title><envar>SGML_CATALOG_FILES</envar></title> - - <para>In order to locate a <filename>catalog</filename> file, your - SGML processor will need to know where to look. Many of them - feature command line parameters for specifying the path to one or - more catalogs.</para> - - <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to - point to the files. This environment variable should consist of a - colon-separated list of catalog files (including their full - path).</para> - - <para>Typically, you will want to include the following files;</para> - - <itemizedlist> - <listitem> - <para><filename>/usr/local/share/sgml/docbook/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/html/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/jade/catalog</filename></para> - </listitem> - </itemizedlist> - - <para>You should <link linkend="sgml-primer-envars">already have done - this</link>.</para> - </sect3> - </sect2> - - <sect2 id="sgml-primer-fpi-alternatives"> - <title>Alternatives to FPIs</title> - - <para>Instead of using an FPI to indicate the DTD that the document - conforms to (and therefore, which file on the system contains the DTD) - you can explicitly specify the name of the file.</para> - - <para>The syntax for this is slightly different;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> - - <para>The <literal>SYSTEM</literal> keyword indicates that the SGML - processor should locate the DTD in a system specific fashion. This - typically (but not always) means the DTD will be provided as a - filename.</para> - - <para>Using FPIs is preferred for reasons of portability. You don't - want to have to ship a copy of the DTD around with your document, and - if you used the <literal>SYSTEM</literal> identifier then everyone - would need to keep their DTDs in the same place.</para> - </sect2> - </sect1> - - <sect1 id="sgml-primer-sgml-escape"> - <title>Escaping back to SGML</title> - - <para>Earlier in this primer I said that SGML is only used when writing a - DTD. This is not strictly true. There is certain SGML syntax that you - will want to be able to use within your documents. For example, - comments can be included in your document, and will be ignored by the - parser. Comments are entered using SGML syntax. Other uses for SGML - syntax in your document will be shown later too.</para> - - <para>Obviously, you need some way of indicating to the SGML processor - that the following content is not elements within the document, but is - SGML that the parser should act upon.</para> - - <para>These sections are marked by <literal><! ... ></literal> in - your document. Everything between these delimiters is SGML syntax as - you might find within a DTD.</para> - - <para>As you may just have realised, the <link - linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link> - is an example of SGML syntax that you need to include in your - document…</para> - </sect1> - - <sect1> - <title>Comments</title> - - <para>Comments are an SGML construction, and are normally only valid - inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape"> - shows, it is possible to use SGML syntax within your document.</para> - - <para>The delimiters for SGML comments is the string - “<literal>--</literal>”. The first occurence of this string - opens a comment, and the second closes it.</para> - - <example> - <title>SGML generic comment</title> - - <programlisting> -<!-- test comment --></programlisting> - - <programlisting><![ CDATA [ -<!-- This is inside the comment --> - -<!-- This is another comment --> - -<!-- This is one way - of doing multiline comments --> - -<!-- This is another way of -- - -- doing multiline comments -->]]></programlisting> - </example> - - <![ %output.print; [ - <important> - <title>Use 2 dashes</title> - - <para>There is a problem with producing the Postscript and PDF versions - of this document. The above example probably shows just one hyphen - symbol, <literal>-</literal> after the <literal><!</literal> and - before the <literal>></literal>.</para> - - <para>You <emphasis>must</emphasis> use two <literal>-</literal>, - <emphasis>not</emphasis> one. The Postscript and PDF versions have - translated the two <literal>-</literal> in the original to a longer, - more professional <emphasis>em-dash</emphasis>, and broken this - example in the process.</para> - - <para>The HTML, plain text, and RTF versions of this document are not - affected.</para> - </important> - ]]> - - <para>If you have used HTML before you may have been shown different rules - for comments. In particular, you may think that the string - <literal><!--</literal> opens a comment, and it is only closed by - <literal>--></literal>.</para> - - <para>This is <emphasis>not</emphasis> the case. A lot of web browsers - have broken HTML parsers, and will accept that as valid. However, the - SGML parsers used by the Documentation Project are much stricter, and - will reject documents that make that error.</para> - - <example> - <title>Errorneous SGML comments</title> - - <programlisting><![ CDATA [ -<!-- This is in the comment -- - - THIS IS OUTSIDE THE COMMENT! - - -- back inside the comment -->]]></programlisting> - - <para>The SGML parser will treat this as though it were actually;</para> - - <programlisting> -<!THIS IS OUTSIDE THE COMMENT></programlisting> - - <para>This is not valid SGML, and may give confusing error - messages.</para> - - <programlisting> -<![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting> - - <para>As the example suggests, <emphasis>do not</emphasis> write - comments like that.</para> - - <programlisting> -<![ CDATA [<!--===================================================-->]]></programlisting> - - <para>That is a (slightly) better approach, but it still potentially - confusing to people new to SGML.</para> - </example> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Add some comments to <filename>example.sgml</filename>, and - check that the file still validates using &man.nsgmls.1;</para> - </step> - - <step> - <para>Add some invalid comments to - <filename>example.sgml</filename>, and see the error messages that - &man.nsgmls.1; gives when it encounters an invalid comment.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Entities</title> - - <para>Entities are a mechanism for assigning names to chunks of content. - As an SGML parser processes your document, any entities it finds are - replaced by the content of the entity.</para> - - <para>This is a good way to have re-usable, easily changeable chunks of - content in your SGML documents. It is also the only way to include one - marked up file inside another using SGML.</para> - - <para>There are two types of entities which can be used in two different - situations; <emphasis>general entities</emphasis> and - <emphasis>parameter entities</emphasis>.</para> - - <sect2 id="sgml-primer-general-entities"> - <title>General Entities</title> - - <para>You can not use general entities in an SGML context (although you - define them in one). They can only be used in your document. - Contrast this with <link - linkend="sgml-primer-parameter-entities">parameter - entities</link>.</para> - - <para>Each general entity has a name. When you want to reference a - general entity (and therefore include whatever text it represents in - your document), you write - <literal>&<replaceable>entity-name</replaceable>;</literal>. For - example, suppose you had an entity called - <literal>current.version</literal> which expanded to the current - version number of your product. You could write;</para> - - <programlisting> -<![ CDATA [<para>The current version of our product is - ¤t.version;.</para>]]></programlisting> - - <para>When the version number changes you can simply change the - definition of the value of the general entity and reprocess your - document.</para> - - <para>You can also use general entities to enter characters that you - could not otherwise include in an SGML document. For example, < - and & can not normally appear in an SGML document. When the SGML - parser sees the < symbol it assumes that a tag (either a start tag - or an end tag) is about to appear, and when it sees the & symbol - it assumes the next text will be the name of an entity.</para> - - <para>Fortunately, you can use the two general entities &lt; and - &amp; whenever you need to include one or other of these </para> - - <para>A general entity can only be defined within an SGML context. - Typically, this is done immediately after the DOCTYPE - declaration.</para> - - <example> - <title>Defining general entities</title> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY current.version "3.0-RELEASE"> -<!ENTITY last.version "2.2.7-RELEASE"> -]>]]></programlisting> - - <para>Notice how the DOCTYPE declaration has been extended by adding a - square bracket at the end of the first line. The two entities are - then defined over the next two lines, before the square bracket is - closed, and then the DOCTYPE declaration is closed.</para> - - <para>The square brackets are necessary to indicate that we are - extending the DTD indicated by the DOCTYPE declaration.</para> - </example> - </sect2> - - <sect2 id="sgml-primer-parameter-entities"> - <title>Parameter entities</title> - - <para>Like <link linkend="sgml-primer-general-entities">general - entities</link>, parameter entities are used to assign names to - reusable chunks of text. However, where as general entities can only - be used within your document, parameter entities can only be used - within an <link linkend="sgml-primer-sgml-escape">SGML - context</link>.</para> - - <para>Parameter entities are defined in a similar way to general - entities. However, instead of using - <literal>&<replaceable>entity-name</replaceable>;</literal> to - refer to them, use - <literal>%<replaceable>entity-name</replaceable>;</literal><footnote> - <para><emphasis>P</emphasis>arameter entities use the - <emphasis>P</emphasis>ercent symbol.</para> - </footnote>. The definition also includes the <literal>%</literal> - between the <literal>ENTITY</literal> keyword and the name of the - entity.</para> - - <example> - <title>Defining parameter entities</title> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % param.some "some"> -<!ENTITY % param.text "text"> -<!ENTITY % param.new "%param.some more %param.text"> - -<!-- %param.new now contains "some more text" --> -]>]]></programlisting> - </example> - - <para>This may not seem particularly useful. It will be.</para> - </sect2> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Add a general entity to - <filename>example.sgml</filename>.</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [ -<!ENTITY version "1.1"> -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <!-- You might well have some comments in here as well --> - - <body> - <p>This is a paragraph containing some text.</p> - - <p>This paragraph contains some more text.</p> - - <p align="right">This paragraph might be right-justified.</p> - - <p>The current version of this document is: &version;</p> - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Validate the document using &man.nsgmls.1;</para> - </step> - - <step> - <para>Load <filename>example.sgml</filename> into your web browser - (you may need to copy it to <filename>example.html</filename> - before your browser recognises it as an HTML document).</para> - - <para>Unless your browser is very advanced, you won't see the entity - reference <literal>&version;</literal> replaced with the - version number. Most web browsers have very simplistic parsers - which do not handle proper SGML<footnote> - <para>This is a shame. Imagine all the problems and hacks (such - as Server Side Includes) that could be avoided if they - did.</para> - </footnote>.</para> - </step> - - <step> - <para>The solution is to <emphasis>normalise</emphasis> your - document using an SGML normaliser. The normaliser reads in valid - SGML and outputs equally valid SGML which has been transformed in - some way. One of the ways in which the normaliser transforms the - SGML is to expand all the entity references in the document, - replacing the entities with the text that they represent.</para> - - <para>You can use &man.sgmlnorm.1; to do this.</para> - - <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen> - - <para>You should find a normalised (i.e., entity references - expanded) copy of your document in - <filename>example.html</filename>, ready to load into your web - browser.</para> - </step> - - <step> - <para>If you look at the output from &man.sgmlnorm.1; you will see - that it does not include a DOCTYPE declaration at the start. To - include this you need to use the <option>-d</option> - option;</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Using entities to include files</title> - - <para>Entities (both <link - linkend="sgml-primer-general-entities">general</link> and <link - linkend="sgml-primer-parameter-entities">parameter</link>) are - particularly useful when used to include one file inside another.</para> - - <sect2 id="sgml-primer-include-using-gen-entities"> - <title>Using general entities to include files</title> - - <para>Suppose you have some content for an SGML book organised into - files, one file per chapter, called - <filename>chapter1.sgml</filename>, - <filename>chapter2.sgml</filename>, and so forth, with a - <filename>book.sgml</filename> file that will contain these - chapters.</para> - - <para>In order to use the contents of these files as the values for your - entities, you declare them with the <literal>SYSTEM</literal> keyword. - This directs the SGML parser to use the contents of the named file as - the value of the entity.</para> - - <example> - <title>Using general entities to include files</title> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> -<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> -<!ENTITY chapter.3 SYSTEM "chapter3.sgml"> -<!-- And so forth --> -]> - -<html> - <!-- Use the entities to load in the chapters --> - - &chapter.1; - &chapter.2; - &chapter.3; -</html>]]></programlisting> - </example> - - <warning> - <para>When using general entities to include other files within a - document, the files being included - (<filename>chapter1.sgml</filename>, - <filename>chapter2.sgml</filename>, and so on) <emphasis>must - not</emphasis> start with a DOCTYPE declaration. This is a syntax - error.</para> - </warning> - </sect2> - - <sect2> - <title>Using parameter entities to include files</title> - - <para>Recall that parameter entities can only be used inside an SGML - context. Why then would you want to include a file within an SGML - context?</para> - - <para>You can use this to ensure that you can reuse your general - entities.</para> - - <para>Suppose that you had many chapters in your document, and you - reused these chapters in two different books, each book organising the - chapters in a different fashion.</para> - - <para>You could list the entities at the top of each book, but this - quickly becomes cumbersome to manage.</para> - - <para>Instead, place the general entity definitions inside one file, - and use a parameter entity to include that file within your - document.</para> - - <example> - <title>Using parameter entities to include files</title> - - <para>First, place your entity definitions in a separate file, called - <filename>chapters.ent</filename>. This file contains the - following;</para> - - <programlisting> -<![ CDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> -<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> -<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting> - - <para>Now create a parameter entity to refer to the contents of the - file. Then use the parameter entity to load the file into the - document, which will then make all the general entities available - for use. Then use the general entities as before;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!-- Define a parameter entity to load in the chapter general entities --> -<!ENTITY % chapters SYSTEM "chapters.ent"> - -<!-- Now use the parameter entity to load in this file --> -%chapters; -]> - -<html> - &chapter.1; - &chapter.2; - &chapter.3; -</html>]]></programlisting> - </example> - </sect2> - - <sect2> - <title>For you to do…</title> - - <sect3> - <title>Use general entities to include files</title> - - <procedure> - <step> - <para>Create three files, <filename>para1.sgml</filename>, - <filename>para2.sgml</filename>, and - <filename>para3.sgml</filename>.</para> - - <para>Put content similar to the following in each file;</para> - - <programlisting> -<![ CDATA [<p>This is the first paragraph.</p>]]></programlisting> - </step> - - <step> - <para>Edit <filename>example.sgml</filename> so that it looks like - this;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.sgml"> -<!ENTITY para2 SYSTEM "para2.sgml"> -<!ENTITY para3 SYSTEM "para3.sgml"> -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>The current version of this document is: &version;</p> - - ¶1; - ¶2; - ¶3; - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by normalising - <filename>example.sgml</filename>.</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> in to your web - browser, and confirm that the - <filename>para<replaceable>n</replaceable>.sgml</filename> files - have been included in <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Use parameter entities to include files</title> - - <note> - <para>You must have taken the previous steps first.</para> - </note> - - <procedure> - <step> - <para>Edit <filename>example.sgml</filename> so that it looks like - this;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % entities SYSTEM "entities.sgml"> %entities; -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>The current version of this document is: &version;</p> - - ¶1; - ¶2; - ¶3; - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Create a new file, <filename>entities.sgml</filename>, with - this content;</para> - - <programlisting> -<![ CDATA [<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.sgml"> -<!ENTITY para2 SYSTEM "para2.sgml"> -<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by normalising - <filename>example.sgml</filename>.</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> in to your web - browser, and confirm that the - <filename>para<replaceable>n</replaceable>.sgml</filename> files - have been included in <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - </sect2> - </sect1> - - <sect1 id="sgml-primer-marked-sections"> - <title>Marked sections</title> - - <para>SGML provides a mechanism to indicate that particular pieces of the - document should be processed in a special way. These are termed - “marked sections”.</para> - - <example> - <title>Structure of a marked section</title> - - <programlisting> -<![ <replaceable>KEYWORD</replaceable> [ - Contents of marked section -]]></programlisting> - </example> - - <para>As you would expect, being an SGML construct, a marked section - starts <literal><!</literal>.</para> - - <para>The first square bracket begins to delimit the marked - section.</para> - - <para><replaceable>KEYWORD</replaceable> describes how this marked - section should be processed by the parser.</para> - - <para>The second square bracket indicates that the content of the marked - section starts here.</para> - - <para>The marked section is finished by closing the two square brackets, - and then returning to the document context from the SGML context with - <literal>></literal></para> - - <sect2> - <title>Marked section keywords</title> - - <sect3> - <title><literal>CDATA</literal>, <literal>RCDATA</literal></title> - - <para>These keywords denote the marked sections <emphasis>content - model</emphasis>, and allow you to change it from the - default.</para> - - <para>When an SGML parser is processing a document, it keeps track - of what is called the “content model”.</para> - - <para>Briefly, the content model describes what sort of content the - parser is expecting to see, and what it will do with it when it - finds it.</para> - - <para>The two content models you will probably find most useful are - <literal>CDATA</literal> and <literal>RCDATA</literal>.</para> - - <para><literal>CDATA</literal> is for “Character Data”. - If the parser is in this content model then it is expecting to see - characters, and characters only. In this model the < and & - symbols lose their special status, and will be treated as ordinary - characters.</para> - - <para><literal>RCDATA</literal> is for “Entity references and - character data” If the parser is in this content model then it - is expecting to see characters <emphasis>and</emphasis> entities. - < loses its special status, but & will still be treated as - starting the beginning of a general entity.</para> - - <para>This is particularly useful if you are including some verbatim - text that contains lots of < and & characters. While you - could go through the text ensuring that every < is converted to a - &lt; and every & is converted to a &amp;, it can be - easier to mark the section as only containing CDATA. When the SGML - parser encounters this it will ignore the < and & symbols - embedded in the content.</para> - - <!-- The nesting of CDATA within the next example is disgusting --> - - <example> - <title>Using a CDATA marked section</title> - - <programlisting> -<para>Here is an example of how you would include some text - that contained many &lt; and &amp; symbols. The sample - text is a fragment of HTML. The surrounding text (<para> and - <programlisting>) are from DocBook.</para> - -<programlisting> - <![ CDATA [ <![ CDATA [ - <p>This is a sample that shows you some of the elements within - HTML. Since the angle brackets are used so many times, it's - simpler to say the whole example is a CDATA marked section - than to use the entity names for the left and right angle - brackets throughout.</p> - - <ul> - <li>This is a listitem</li> - <li>This is a second listitem</li> - <li>This is a third listitem</li> - </ul> - - <p>This is the end of the example.</p>]]> - ]]> -</programlisting></programlisting> - - <para>If you look at the source for this document you will see this - technique used throughout.</para> - </example> - </sect3> - - <sect3> - <title><literal>INCLUDE</literal> and - <literal>IGNORE</literal></title> - - <para>If the keyword is <literal>INCLUDE</literal> then the contents - of the marked section will be processed. If the keyword is - <literal>IGNORE</literal> then the marked section is ignored and - will not be processed. It will not appear in the output.</para> - - <example> - <title>Using <literal>INCLUDE</literal> and - <literal>IGNORE</literal> in marked sections</title> - - <programlisting> -<![ INCLUDE [ - This text will be processed and included. -]]> - -<![ IGNORE [ - This text will not be processed or included. -]]></programlisting> - </example> - - <para>By itself, this isn't too useful. If you wanted to remove text - from your document you could cut it out, or wrap it in - comments.</para> - - <para>It becomes more useful when you realise you can use <link - linkend="sgml-primer-parameter-entities">parameter entities</link> - to control this. Remember that parameter entities can only be used - in SGML contexts, and the keyword of a marked section - <emphasis>is</emphasis> an SGML context.</para> - - <para>For example, suppose that you produced a hard-copy version of - some documentation and an electronic version. In the electronic - version you wanted to include some extra content that wasn't to - appear in the hard-copy.</para> - - <para>Create a parameter entity, and set it's value to - <literal>INCLUDE</literal>. Write your document, using marked - sections to delimit content that should only appear in the - electronic version. In these marked sections use the parameter - entity in place of the keyword.</para> - - <para>When you want to produce the hard-copy version of the document, - change the parameter entity's value to <literal>IGNORE</literal> and - reprocess the document.</para> - - <example> - <title>Using a parameter entity to control a marked - section</title> - - <programlisting> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % electronic.copy "INCLUDE"> -]]> - -... - -<![ %electronic.copy [ - This content should only appear in the electronic - version of the document. -]]></programlisting> - - <para>When producing the hard-copy version, change the entity's - definition to;</para> - - <programlisting> -<!ENTITY % electronic.copy "IGNORE"></programlisting> - - <para>On reprocessing the document, the marked sections that use - <literal>%electronic.copy</literal> as their keyword will be - ignored.</para> - </example> - </sect3> - </sect2> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Create a new file, <filename>section.sgml</filename>, that - contains the following;</para> - - <programlisting> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % text.output "INCLUDE"> -]> - -<html> - <head> - <title>An example using marked sections</title> - </head> - - <body> - <p>This paragraph <![ CDATA [contains many < - characters (< < < < <) so it is easier - to wrap it in a CDATA marked section ]]></p> - - <![ IGNORE [ - <p>This paragraph will definitely not be included in the - output.</p> - ]]> - - <![ <![ CDATA [%text.output]]> [ - <p>This paragraph might appear in the output, or it - might not.</p> - - <p>Its appearance is controlled by the <![CDATA[%text.output]]> - parameter entity.</p> - ]]> - </body> -</html></programlisting> - </step> - - <step> - <para>Normalise this file using &man.sgmlnorm.1; and examine the - output. Notice which paragraphs have appeared, which have - disappeared, and what has happened to the content of the CDATA - marked section.</para> - </step> - - <step> - <para>Change the definition of the <literal>text.output</literal> - entity from <literal>INCLUDE</literal> to - <literal>IGNORE</literal>. Re-normalise the file, and examine the - output to see what has changed. </para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Conclusion</title> - - <para>That is the conclusion of this SGML primer. For reasons of space - and complexity several things have not been covered in depth (or at - all). However, the previous sections cover enough SGML for you to be - able to follow the organisation of the FDP documentation.</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: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en/tutorials/docproj-primer/stylesheets/chapter.sgml b/en/tutorials/docproj-primer/stylesheets/chapter.sgml deleted file mode 100644 index bc3a770c45..0000000000 --- a/en/tutorials/docproj-primer/stylesheets/chapter.sgml +++ /dev/null @@ -1,70 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.2 1999-07-14 19:22:45 nik Exp $ ---> - -<chapter id="stylesheets"> - <title>* Stylesheets</title> - - <para>SGML says nothing about how a document should be displayed to the - user, or rendered on paper. To do that, various languages have been - developed to describe stylesheets, including DynaText, Panorama, SPICE, - JSSS, FOSI, CSS, and DSSSL.</para> - - <para>For DocBook, we are using stylesheets written in DSSSL. For HTML we - are using CSS.</para> - - <sect1> - <title>* DSSSL</title> - - <para>The Documentation Project uses a slightly customised version of - Norm Walsh's modular DocBook stylesheets.</para> - - <para>These can be found in - <filename>textproc/dsssl-docbook-modular</filename>.</para> - </sect1> - - <sect1> - <title>* CSS</title> - - <para></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: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en/tutorials/docproj-primer/the-faq/chapter.sgml b/en/tutorials/docproj-primer/the-faq/chapter.sgml deleted file mode 100644 index 664c9bbf5e..0000000000 --- a/en/tutorials/docproj-primer/the-faq/chapter.sgml +++ /dev/null @@ -1,49 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.2 1999-07-14 19:20:30 nik Exp $ ---> - -<chapter id="the-faq"> - <title>* The FAQ</title> - - <para></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: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en/tutorials/docproj-primer/the-handbook/chapter.sgml b/en/tutorials/docproj-primer/the-handbook/chapter.sgml deleted file mode 100644 index 004ccb34ef..0000000000 --- a/en/tutorials/docproj-primer/the-handbook/chapter.sgml +++ /dev/null @@ -1,282 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.5 1999-07-30 20:51:00 nik Exp $ ---> - -<chapter id="the-handbook"> - <title>* The Handbook</title> - - <sect1> - <title>Logical structure</title> - - <para>The Handbook is written to comply with the FreeBSD DocBook extended - DTD.</para> - - <para>The Handbook is organised as a DocBook <sgmltag>book</sgmltag>. It - is then divided into <sgmltag>part</sgmltag>s, each of which may contain - several <sgmltag>chapter</sgmltag>s. <sgmltag>chapter</sgmltag>s are - further subdivided into sections (<sgmltag>sect1</sgmltag>) and - subsections (<sgmltag>sect2</sgmltag>, <sgmltag>sect3</sgmltag>) and so - on.</para> - </sect1> - - <sect1> - <title>Physical organisation</title> - - <para>The Handbook (and its translations) are in the - <filename>doc/<replaceable>language</replaceable>/handbook</filename> - subdirectory of the main CVS - repository. <replaceable>language</replaceable> corresponds to the ISO - language code for that translation, <literal>en</literal> for English, - <literal>ja</literal> for Japanese, and so on.</para> - - <para>There are a number of files and directories within the - <filename>handbook</filename> directory.</para> - - <note> - <para>The Handbook's organisation may change over time, and this - document may lag in detailing the organisational changes. If you have - any questions about how the Handbook is organised, please contact the - FreeBSD Documentation Project, <email>doc@FreeBSD.ORG</email>.</para> - </note> - - <sect2> - <title><filename>Makefile</filename></title> - - <para>The <filename>Makefile</filename> defines the rules that are used - to convert the Handbook from its source form (DocBook) to a number of - other target formats (including HTML, PostScript, and plain - text).</para> - - <para>A more detailed description of the <filename>Makefile</filename> - is in <xref linkend="the-handbook-converting">.</para> - </sect2> - - <sect2> - <title><filename>handbook.sgml</filename></title> - - <para>This is the top level document in the Handbook. It contains the - Handbook's <link linkend="sgml-primer-doctype-declaration">DOCTYPE - declaration</link>, as well as the elements that describe the - Handbook's structure.</para> - - <para><filename>handbook.sgml</filename> uses <link - linkend="sgml-primer-parameter-entities">parameter entities</link> - to load in the files with the <filename>.ent</filename> extension. - These files (described later) then define <link - linkend="sgml-primer-general-entities">general entities</link> that - are used throughout the rest of the Handbook.</para> - </sect2> - - <sect2> - <title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title> - - <para>Each chapter in the Handbook is stored in a file called - <filename>chapter.sgml</filename> in a separate directory from the - other chapters. Each directory is named after the value of the - <literal>id</literal> attribute on the <sgmltag>chapter</sgmltag> - element.</para> - - <para>For example, if one of the chapter files contains:</para> - - <programlisting><![ CDATA [ -<chapter id="kernelconfiguration"> -... -</chapter>]]></programlisting> - - <para>then it will be called <filename>chapter.sgml</filename> in the - <filename>kernelconfiguration</filename> directory. In general, the - entire contents of the chapter will be held in this file.</para> - - <para>When the HTML version of the Handbook is produced, this will yield - <filename>kernelconfiguration.html</filename>. This is because of the - <literal>id</literal> value, and is not related to the name of the - directory.</para> - - <para>In earlier versions of the Handbook the files were stored in the - same directory as <filename>handbook.sgml</filename>, and named after - the value of the <literal>id</literal> attribute on the file's - <sgmltag>chapter</sgmltag> element. Moving them in to separate - directories prepares for future plans for the Handbook. Specifically, - it will soon be possible to include images in each chapter. It - makes more sense for each image to be stored in a directory with the - text for the chapter than to try and keep the text for all the - chapters, and all the images, in one large directory. Namespace - collisions would be inevitable, and it is easier to work with several - directories with a few files in them than it is to work with one - directory that has many files in it.</para> - - <para>A brief look will show that there are many directories with - individual <filename>chapter.sgml</filename> files, including - <filename>basics/chapter.sgml</filename>, - <filename>introduction/chapter.sgml</filename>, and - <filename>printing/chapter.sgml</filename>.</para> - - <important> - <para>Chapters and/or directories should not be named in a fashion - that reflects their ordering within the Handbook. This ordering - might change as the content within the Handbook is reorganised; this - sort of reorganistion should not (generally) include the need to - rename files (unless entire chapters are being promoted or demoted - within the hierarchy).</para> - </important> - - <para>Each <filename>chapter.sgml</filename> file will not be a complete - SGML document. In particular, they will not have their own DOCTYPE - line at the start of the file.</para> - - <para>This is unfortunate for two reasons;</para> - - <itemizedlist> - <listitem> - <para>It makes it impossible to treat these as generic SGML files - and simply convert them to HTML, RTF, PS, and other formats in the - same way the main Handbook is generated. This - <emphasis>would</emphasis> force you to rebuild the Handbook every - time you want to see the effect a change as had on just one - chapter.</para> - </listitem> - - <listitem> - <para>Emacs' <literal>sgml-mode</literal> can not use it to - determine the DTD to use, losing useful benefits of - <literal>sgml-mode</literal> (element completion, automatic - validation, and so on).</para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1> - <title>Style guide</title> - - <para>To keep the source for the Handbook consistent when many different - people are editing it, please follow these style conventions.</para> - - <sect2> - <title>Letter case</title> - - <para>Tags are entered in lower case, <literal><para></literal>, - <emphasis>not</emphasis> <literal><PARA></literal>.</para> - - <para>Text that appears in SGML contexts is generally written in upper - case, <literal><!ENTITY…></literal>, and - <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> - <literal><!entity…></literal> and - <literal><!doctype…></literal>.</para> - </sect2> - - <sect2> - <title>Indentation</title> - - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> - - <para>Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. Content - within elements should be indented by two spaces if the content runs - over more than one line.</para> - - <para>For example, the source for this section looks something - like;</para> - - <programlisting> -<![ CDATA [+--- This is column 0 -V -<chapter> - <title>...</title> - - <sect1> - <title>...</title> - - <sect2> - <title>Indentation</title> - - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> - - <para>Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. Content - within elements should be indented by two spaces if the content runs - over more than one line.</para> - - ... - </sect2> - </sect1> -</chapter>]]></programlisting> - - <para>If you use <application>Emacs</application> or - <application>Xemacs</application> to edit the files then - <literal>sgml-mode</literal> should be loaded automatically, and the - Emacs local variables at the bottom of each file should enforce these - styles.</para> - </sect2> - - <sect2> - <title>White space changes</title> - - <para>When committing changes, <emphasis>do not commit changes to the - content at the same time as changes to the - formatting</emphasis>.</para> - - <para>This is so that the teams that convert the Handbook to other - languages can quickly see what content has actually changed in your - commit, without having to decide whether a line has changed because of - the content, or just because it has been refilled.</para> - - <para>For example, if you have added two sentances to a paragraph, such - that the line lengths on the paragraph now go over 80 columns, first - commit your change with the too-long line lengths. Then fix the line - wrapping, and commit this second change. In the commit message for - the second change, be sure to indicate that this is a whitespace-only - change, and that the translation team can ignore it.</para> - </sect2> - </sect1> - - <sect1 id="the-handbook-converting"> - <title>Converting the Handbook to other formats</title> - - <para></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: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en/tutorials/docproj-primer/the-website/chapter.sgml b/en/tutorials/docproj-primer/the-website/chapter.sgml deleted file mode 100644 index cd07de07af..0000000000 --- a/en/tutorials/docproj-primer/the-website/chapter.sgml +++ /dev/null @@ -1,49 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.2 1999-07-14 19:22:46 nik Exp $ ---> - -<chapter id="the-website"> - <title>* The Website</title> - - <para></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: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en/tutorials/docproj-primer/tools/chapter.sgml b/en/tutorials/docproj-primer/tools/chapter.sgml deleted file mode 100644 index 72eeddf8f6..0000000000 --- a/en/tutorials/docproj-primer/tools/chapter.sgml +++ /dev/null @@ -1,284 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.4 1999-07-14 19:19:24 nik Exp $ ---> - -<chapter id="tools"> - <title>Tools</title> - - <para>The FDP uses a number of different software tools to help - manage the FreeBSD documentation, convert it to different output - formats, and so on. You will need to use these tools yourself if - you are to work with the FreeBSD documentation.</para> - - <para>All these tools are available as FreeBSD Ports and Packages, - greatly simplifying the work you have to do to install - them.</para> - - <para>You will need to install these tools before you work through - any of the examples in later chapters. The actual usage of these - tools is covered in these later chapters.</para> - - <important> - <title>Use <filename>textproc/docproj</filename> if possible</title> - - <para>You can save yourself a lot of time if you install the - <filename>textproc/docproj</filename> port. This is a - <emphasis>meta-port</emphasis> which does not contain any software - itself. Instead, it depends on various other ports being installed - correctly. Installing this port <emphasis>should</emphasis> - automatically download and install all of the packages listed in this - chapter that you need that are missing from your system.</para> - - <para>One of the packages that you might need is the JadeTeX macro set. - In turn, this macro set requires that TeX is installed. TeX is a large - package, and you only need it if you want to produce Postscript or PDF - output.</para> - - <para>To save yourself time and space you must specify whether or not you - want JadeTeX (and therefore TeX) installed when you install this port. - Either do; - - <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen> - - or - - <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen> - - as necessary.</para> - </important> - - <sect1> - <title>Mandatory tools</title> - - <sect2> - <title>Software</title> - - <para>These programs are required before you can usefully work with - the FreeBSD documentation. They are all included in - <filename>textproc/docproj</filename>.</para> - - <variablelist> - <varlistentry> - <term><application>SP</application> - (<filename>textproc/sp</filename>)</term> - - <listitem> - <para>A suite of applications, including a validating SGML parser, - and an SGML normaliser.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Jade</application> - (<filename>textproc/jade</filename>)</term> - - <listitem> - <para>A DSSSL implementation. Used for converting marked up - documents to other formats, including HTML and TeX.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Tidy</application> - (<filename>www/tidy</filename>)</term> - - <listitem> - <para>An HTML 'pretty printer', used to reformat some of the - automatically generated HTML so that it is easier to - follow.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Lynx</application> - (<filename>www/lynx-current</filename>)</term> - - <listitem> - <para>A text-mode WWW browser, &man.lynx.1; can also convert - HTML files to plain text.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>DTDs and Entities</title> - - <para>These are the DTDs and entity sets used by the FDP. They need to - be installed before you can work with any of the documentation.</para> - - <variablelist> - <varlistentry> - <term>HTML DTD (<filename>textproc/html</filename>)</term> - - <listitem> - <para>HTML is the markup language of choice for the World Wide - Web, and is used throughout the FreeBSD web site.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LinuxDoc DTD (<filename>textproc/linuxdoc</filename>)</term> - - <listitem> - <para>Some FreeBSD documentation is marked up in LinuxDoc. The - FDP is actively migrating from LinuxDoc to DocBook.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>DocBook DTD (<filename>textproc/docbook</filename>)</term> - - <listitem> - <para>DocBook is designed for marking up technical documentation, - and the FDP is migrating from LinuxDoc to DocBook. At the time - of writing, this document, and the FreeBSD Handbook are marked - up in DocBook.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ISO 8879 entities - (<filename>textproc/iso8879</filename>)</term> - - <listitem> - <para>19 of the ISO 8879:1986 character entity sets used by many - DTDs. Includes named mathematical symbols, additional - characters in the 'latin' character set (accents, diacriticals, - and so on), and greek symbols.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Stylesheets</title> - - <para>The stylesheets are used when converting and formatting the - documentation for display on screen, printing, and so on.</para> - - <variablelist> - <varlistentry> - <term>Modular DocBook Stylesheets - (<filename>textproc/dsssl-docbook-modular</filename>)</term> - - <listitem> - <para>The Modular DocBook Stylesheets are used when converting - documentation marked up in DocBook to other formats, such as - HTML, or RTF.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1> - <title>Optional tools</title> - - <para>You do not need to have any of the following installed. However, - you may find it easier to work with the documentation if you do, and - they may give you more flexibility in the output formats that can be - generated.</para> - - <sect2> - <title>Software</title> - - <variablelist> - <varlistentry> - <term><application>JadeTeX</application> and - <application>teTeX</application> - (<filename>print/jadetex</filename> and - <filename>print/teTeX-beta</filename>)</term> - - <listitem> - <para><application>Jade</application> and - <application>teTeX</application> are used to convert DocBook - documents to DVI, Postscript, and PDF formats. The - <application>JadeTeX</application> macros are needed in order to - do this.</para> - - <para>If you do not intend to convert your documentation to one of - these formats (i.e., HTML, plain text, and RTF are sufficient) - then you do not need to install - <application>JadeTeX</application> and - <application>teTeX</application>. This can be a significant - space and time saver, as <application>teTeX</application> is - over 30MB in size.</para> - - <important> - <para>If you decide to install - <application>JadeTeX</application> and - <application>teTeX</application> then you will need to - configure <application>teTeX</application> after - <application>JadeTeX</application> has been installed. - <filename>print/jadetex/pkg/MESSAGE</filename> contains - detailed instructions explaining what you need to do.</para> - </important> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Emacs</application> or - <application>xemacs</application> - (<filename>editors/emacs</filename> or - <filename>editors/xemacs</filename>)</term> - - <listitem> - <para>Both these editors include a special mode for editing - documents marked up according to an SGML DTD. This mode - includes commands to reduce the amount of typing you need, and - help reduce the possibility of errors.</para> - - <para>You do not need to use them, any text editor can be used to - edit marked up documents. You may find they make you - efficient.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>If anyone has recommendations for other software that is useful - when manipulating SGML documents, please let Nik Clayton - (<email>nik@freebsd.org</email>) know, so they can be added to this - list.</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: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en/tutorials/docproj-primer/translations/chapter.sgml b/en/tutorials/docproj-primer/translations/chapter.sgml deleted file mode 100644 index 1b3526ab7c..0000000000 --- a/en/tutorials/docproj-primer/translations/chapter.sgml +++ /dev/null @@ -1,474 +0,0 @@ -<!-- Copyright (c) 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.1 1999-07-14 22:30:26 nik Exp $ ---> - -<chapter id="translations"> - <title>Translations</title> - - <para>This is the FAQ for people translating the FreeBSD documentation - (FAQ, Handbook, tutorials, man pages, and others) to different - languages.</para> - - <para>It is <emphasis>very</emphasis> heavily based on the translation FAQ - from the FreeBSD German Documentation Project, originally written by Frank - Grnder <email>elwood@mc5sys.in-berlin.de</email> and translated back to - English by Bernd Warken <email>bwarken@mayn.de</email>.</para> - - <para>The FAQ maintainer is Nik Clayton - <email>nik@FreeBSD.org</email>.</para> - - <qandaset> - <qandaentry> - <question> - <para>Why a FAQ?</para> - </question> - - <answer> - <para>More and more people are approaching the freebsd-doc mailing - list and volunteering to translate FreeBSD documentation to other - languages. This FAQ aims to answer their questions so they can start - translating documentation as quickly as possible.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase> - mean?</para> - </question> - - <answer> - <para><phrase>i18n</phrase> means - <phrase>internationalisation</phrase> and <phrase>l10n</phrase> - means <phrase>localisation</phrase>. They are just a convenient - shorthand.</para> - - <para><phrase>i18n</phrase> can be read as “i” followed by - 18 letters, followed by “n”. Similarly, - <phrase>l10n</phrase> is “l” followed by 10 letters, - followed by “n”.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Is there a mailing list for translators?</para> - </question> - - <answer> - <para>Yes, <email>freebsd-translate@ngo.org.uk</email>. Subscribe by - sending a message to - <email>freebsd-translate-request@ngo.org.uk</email> with the word - <literal>subscribe</literal> in the body of the message.</para> - - <para>You will receive a reply asking you to confirm your subscription - (in exactly the same manner as the the FreeBSD lists at <hostid - role="domainname">FreeBSD.org</hostid>).</para> - - <para>The primary language of the mailing list is English. However, - posts in other languages will be accepted. The mailing list is not - moderated, but you need to be a member of the list before you can - post to it.</para> - - <para>The mailing list is archived, but they are not currently - searchable. Sending the message <literal>help</literal> to - <email>majordomo@ngo.org.uk</email> will send back instructions on - how to access the archive.</para> - - <para>It is expected that the mailing list will transfer to <hostid - role="domainname">FreeBSD.org</hostid> and therefore become - <emphasis>official</emphasis> in the near future.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Are more translators needed?</para> - </question> - - <answer> - <para>Yes. The more people work on translation the faster it gets - done, and the faster changes to the English documentation are - mirrored in the translated documents.</para> - - <para>You do not have to be a professional translator to be able to - help.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What languages do I need to know?</para> - </question> - - <answer> - <para>Ideally, you will have a good knowledge of written English, and - obviously you will need to be fluent in the language you are - translating to.</para> - - <para>English is not strictly necessary. For example, you could do a - Hungarian translation of the FAQ from the Spanish - translation.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What software do I need to know?</para> - </question> - - <answer> - <para>It is strongly recommended that you maintain a local copy of the - FreeBSD CVS repository (at least the documentation part) either - using <application>CTM</application> or - <application>CVSup</application>. The "Staying current with FreeBSD" - chapter in the Handbook explains how to use these - applications.</para> - - <para>You should be comfortable using <application>CVS</application>. - This will allow you to see what has changed between different - versions of the files that make up the documentation.</para> - - <para>[XXX To Do -- write a tutorial that shows how to use CVSup to - get just the documentation, check it out, and see what's changed - between two arbitrary revisions]</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I find out who else might be translating to the same - language?</para> - </question> - - <answer> - <para>The <ulink - url="http://www.freebsd.org/docproj/translations.html">Documentation - Project translations page</ulink> lists the translation efforts - that are currently known about. If someone else is already working - on translating documentation to your language, please don't - duplicate their efforts. Instead, contact them to see how you can - help.</para> - - <para>If no one is listed on that page as translating for your - language then send a message to - <email>freebsd-doc@freebsd.org</email> in case someone else is - thinking of doing a translation, but hasn't announced it yet.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>No one else is translating to my language. What do I do?</para> - </question> - - <answer> - <para>Congratulations, you have just started the “FreeBSD - <replaceable>your-language-here</replaceable> Documentation - Translation Project”. Welcome aboard.</para> - - <para>First, decide whether or not you've got the time to spare. Since - you are the only person working on your language at the moment it is - going to be your responsibility to publicise your work and - coordinate any volunteers that might want to help you.</para> - - <para>Write an e-mail to the Documentation Project mailing list, - announcing that you are going to translate the documentation, so the - Documentation Project translations page can be maintained.</para> - - <para>You should subscribe to the - <email>freebsd-translate@ngo.org.uk</email> mailing list (as - described earlier).</para> - - <para>If there is already someone in your country providing FreeBSD - mirroring services you should contact them and ask if they can - provide some webspace for your project, and possibly an e-mail - address or mailing list services.</para> - - <para>Then pick a document and start translating. It is best to start - with something fairly small—either the FAQ, or one of the - tutorials.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I've translated some documentation, where do I send it?</para> - </question> - - <answer> - <para>That depends. If you are already working with a translation team - (such as the Japanese team, or the German team) then they will have - their own procedures for handling submitted documentation, and these - will be outlined on their web pages.</para> - - <para>If you are the only person working on a particular language (or - you are responsible for a translation project and want to submit - your changes back to the FreeBSD project) then you should send your - translation to the FreeBSD project (see the next question).</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I'm the only person working on translating to this language, how - do I submit my translation?</para> - - <para>or</para> - - <para>We're a translation team, and want to submit documentation that - our members have translated for us?</para> - </question> - - <answer> - <para>First, make sure your translation is organised properly. This - means that it should drop in to the existing documentation tree and - build straight away.</para> - - <para>Currently, the FreeBSD documentation is stored in a top level - directory called <filename>doc/</filename>. Directories below this - are named according to the language code they are written in, as - defined in ISO639 (<filename>/usr/share/misc/iso639</filename> on a - version of FreeBSD newer than 20th January 1999).</para> - - <para>If your language can be encoded in different ways (for example, - Chinese) then there should be directories below this, one for each - encoding format you have provided.</para> - - <para>Finally, you should have directories for each document.</para> - - <para>For example, a hypothetical Swedish translation might look - like</para> - - <programlisting> doc/ - sv/ - Makefile - FAQ/ - Makefile - *.sgml</programlisting> - - <para><literal>sv</literal> is the ISO639 code for Swedish. Note the - two Makefiles, which will be used to build the documentation. There - is no separate language code for Swedish, so there is no - intermittent directory between the "sv" and "FAQ" - directories<footnote> - <para>This directory structure is going to change radically quite - soon. Please see the on-going discussions on the - <email>doc@FreeBSD.org</email> mailing list for more - information.</para> - </footnote>.</para> - - <para>Use &man.tar.1; and &man.gzip.1; to compress up your - documentation, and send it to the project.</para> - - <screen>&prompt.user; <userinput>cd doc</userinput> -&prompt.user; <userinput>tar cf swedish-docs.tar sv</userinput> -&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen> - - <para>Put <filename>swedish-docs.tar.gz</filename> somewhere. If you - do not have access to your own webspace (perhaps your ISP does not - let you have any) then you can e-mail Nik Clayton - <email>nik@FreeBSD.org</email>, and arrange to e-mail the files - when it is convenient.</para> - - <para>Either way, you should use &man.send-pr.1; to submit a report - indicating that you have submitted the documentation. It would be - very helpful if you could get other people to look over your - translation and double check it first, since it is unlikely that the - person committing it will be fluent in the language.</para> - - <para>Someone (probably the Documentation Project Manager, currently - Nik Clayton <email>nik@FreeBSD.org</email>) will then take your - translation and confirm that it builds. In particular, the - following things will be looked at:</para> - - <orderedlist> - <listitem> - <para>Do all your files use RCS strings (such as "ID").</para> - </listitem> - - <listitem> - <para>Does <command>make all</command> in the - <filename>sv</filename> directory work correctly.</para> - </listitem> - - <listitem> - <para>Does <command>make install</command> work correctly.</para> - </listitem> - </orderedlist> - - <para>If there are any problems then whoever is looking at the - submission will get back to you to try and work them out.</para> - - <para>If there are no problems then your translation will be committed - as soon as possible.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I include language or country specific text in my - translation?</para> - </question> - - <answer> - <para>We would prefer that you did not.</para> - - <para>For example, suppose that you are translating the Handbook to - Korean, and want to include a section about retailers in Korea in - your Handbook.</para> - - <para>There's no real reason why that information should not be in the - English (or German, or Spanish, or Japanese, or …) versions - as well. It is feasible that an English speaker in Korea might try - and pick up a copy of FreeBSD whilst over there. It also helps - increase FreeBSD's perceived presence around the globe, which is not - a bad thing.</para> - - <para>If you have country specific information, please submit it as a - change to the English Handbook (using &man.send-pr.1;) and then - translate the change back to your language in the translated - Handbook.</para> - - <para>Thanks.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How should language specific characters be included?</para> - - <para>Non-ASCII characters in the documentation should be included - using SGML entities.</para> - - <para>Briefly, these look like an ampersand (&), the name of the - entity, and a semi-colon (;).</para> - - <para>The entity names are defined in ISO8879, which is in the ports - tree as <filename>textproc/iso8879</filename>.</para> - - <para>A few examples include</para> - - <segmentedlist> - <seglistitem> - <seg>&eacute;</seg> - <seg>é</seg> - <seg>Small “e” with an acute accent</seg> - </seglistitem> - - <seglistitem> - <seg>&Eacute;</seg> - <seg>É</seg> - <seg>Large “E” with an acute accent</seg> - </seglistitem> - - <seglistitem> - <seg>&uuml;</seg> - <seg>ü</seg> - <seg>Small “u” with an umlaut</seg> - </seglistitem> - </segmentedlist> - - <para>After you have installed the iso8879 port, the files in - <filename>/usr/local/share/sgml/iso8879</filename> contain the - complete list.</para> - </question> - </qandaentry> - - <qandaentry> - <question> - <para>Addressing the reader</para> - </question> - - <answer> - <para>In the English documents, the reader is addressed as - “you”, there is no formal/informal distinction as there - is in some languages.</para> - - <para>If you are translating to a language which does distinguish, use - whichever form is typically used in other technical documentation in - your language. If in doubt, use a mildly polite form.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Do I need to include any additional information in my - translations?</para> - </question> - - <answer> - <para>Yes.</para> - - <para>The header of the English version of each document will look - something like this;</para> - - <programlisting><![ CDATA [<!-- - The FreeBSD Documentation Project - - $Id: chapter.sgml,v 1.11 1999/06/20 21:18:57 billf Exp $ --->]]></programlisting> - - <para>The exact boilerplate may change, but it will always include an - Id line and the phrase <literal>The FreeBSD Documentation - Project</literal>.</para> - - <para>Your translated documents should include their own Id line, and change the - <literal>FreeBSD Documentation Project</literal> line to - <literal>The FreeBSD <replaceable>language</replaceable> - Documentation Project</literal>.</para> - - <para>In addition, you should add a third line which indicates which - revision of the English text this is based on.</para> - - <para>So, the Spanish version of this file might start</para> - - <programlisting><![ CDATA [<!-- - The FreeBSD Spanish Documentation Project - - $Id: chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $ - Original revision: 1.11 --->]]></programlisting> - </answer> - </qandaentry> - </qandaset> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en/tutorials/docproj-primer/writing-style/chapter.sgml b/en/tutorials/docproj-primer/writing-style/chapter.sgml deleted file mode 100644 index c1e9fbde52..0000000000 --- a/en/tutorials/docproj-primer/writing-style/chapter.sgml +++ /dev/null @@ -1,143 +0,0 @@ -<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) 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 compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.3 1999-07-30 21:09:07 nik Exp $ ---> - -<chapter id="writing-style"> - <title>Writing style</title> - - <para>In order to promote consistency between the myriad authors of the - FreeBSD documentation, some guidelines have been drawn up for authors to - follow.</para> - - <variablelist> - <varlistentry> - <term>Do not use contractions</term> - - <listitem> - <para>Do not use contractions. Always spell the phrase out in full. - “Don't use contractions” would be wrong.</para> - - <para>Avoiding contractions makes for a more formal tone, is more - precise, and slightly easier for translators.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use the serial comma</term> - - <listitem> - <para>In a list of items within a paragraph, seperate each item from - the others with a comma. Seperate the last item from the others with - a comma and the word “and”.</para> - - <para>For example, look at the following quote;</para> - - <blockquote> - <para>This is a list of one, two and three items.</para> - </blockquote> - - <para>Is this a list of three items, “one”, - “two”, and “three”, or a list of two items, - “one” and “two and three”?</para> - - <para>It is better to be explicit and include a serial comma;</para> - - <blockquote> - <para>This is a list of one, two, and three items.</para> - </blockquote> - </listitem> - </varlistentry> - - <varlistentry> - <term>Avoid redundant phrases</term> - - <listitem> - <para>Try not to use redundant phrases. In particular, “the - command”, “the file”, and “man - command” are probably redundant.</para> - - <para>These two examples show this for commands. The second example - is preferred.</para> - - <informalexample> - <para>Use the command <command>cvsup</command> to update your - sources</para> - </informalexample> - - <informalexample> - <para>Use <command>cvsup</command> to update your sources</para> - </informalexample> - - <para>These two examples show this for filenames. The second example - is preferred.</para> - - <informalexample> - <para>… in the filename - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <informalexample> - <para>… in - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <para>These two examples show this for manual references. The second - example is preferred (the second example uses - <sgmltag>citerefentry</sgmltag>).</para> - - <informalexample> - <para>See <command>man csh</command> for more - information.</para> - </informalexample> - - <informalexample> - <para>See &man.csh.1;</para> - </informalexample> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information about writing style, see <ulink - url="http://www.columbia.edu/acis/bartleby/strunk/">Elements of - Style</ulink>, by William Strunk.</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: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en/tutorials/fonts/Makefile b/en/tutorials/fonts/Makefile deleted file mode 100644 index 260184f87c..0000000000 --- a/en/tutorials/fonts/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= fonts.docb -INDEXLINK= fonts.html - -.include "../../web.mk" diff --git a/en/tutorials/fonts/fonts.docb b/en/tutorials/fonts/fonts.docb deleted file mode 100644 index 75d01279be..0000000000 --- a/en/tutorials/fonts/fonts.docb +++ /dev/null @@ -1,951 +0,0 @@ -<!-- $Id: fonts.docb,v 1.3 1999-08-06 17:35:18 nik Exp $ --> -<!-- The FreeBSD Documentation Project --> -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> - -<!-- Recently, I wanted to figure out how to use some additional fonts that - I had accumulated. I finally figured out *how to do it* from the various - man pages and documentation. Since it might be of use to other users, - and I didn't see any reference to this topic in the FAQ or handbook, I - thought I'd try my hand at a simple cookbook tutorial addressing the - use of fonts. I have included my unanswered questions at the end of - the document. - - Anyway, here's what I put together. This is my present understanding of - fonts and how to use them with FreeBSD. I am sure that there are errors or - misunderstandings, but it contains enough valid information to allow the - use of additional fonts with Ghostscript, X11 and Groff. This is my first - attempt to write anything along the lines of a tutorial/FAQ, so I am sure - it is pretty raw. There are probably better ways to do some of this stuff, - and I would welcome being corrected. - --> - -<book> - -<bookinfo> -<bookbiblio> -<title>Fonts and FreeBSD</title> -<subtitle>A Tutorial</subtitle> - -<authorgroup> -<author> -<firstname>Dave</firstname> -<surname>Bodenstab</surname> -<affiliation> -<address><email>imdave@synet.net</email></address> -</affiliation> -</author> -</authorgroup> - -<pubdate>Wed Aug 7, 1996</pubdate> - -<abstract><para>This document contains a description of the various -font files that may be used with FreeBSD and the syscons driver, X11, -Ghostscript and Groff. Cookbook examples are provided for switching -the syscons display to 80x60 mode, and for using type 1 fonts with -the above application programs.</para></abstract> - -</bookbiblio> -</bookinfo> - -<chapter> -<title>Introduction</title> - -<para>There are many sources of fonts available, and one might ask -how they might be used with FreeBSD. The answer can be found by -carefully searching the documentation for the component that one -would like to use. This is very time consuming, so this tutorial is -an attempt to provide a shortcut for others who might be -interested.</para> - -</chapter> - -<chapter> -<title>Basic terminology</title> - -<para>There are many different font formats and associated font file -suffixes. A few that will be addressed here are: -<variablelist> - -<varlistentry><term><filename>.pfa</>, <filename>.pfb</></term> - -<listitem><para>Postscript type 1 fonts. The <filename>.pfa</filename> is the -<emphasis>A</emphasis>scii form and <filename>.pfb</filename> the -<emphasis>B</emphasis>inary form.</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.afm</></term> - -<listitem><para>The font metrics associated with a type 1 -font.</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.pfm</></term> - -<listitem><para>The printer font metrics associated with a type 1 -font.</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.ttf</></term> - -<listitem><para>A TrueType font</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.fot</></term> - -<listitem><para>An indirect reference to a TrueType font (not an -actual font)</para></listitem> - -</varlistentry> - -<varlistentry><term><filename>.fon</>, <filename>.fnt</></term> - -<listitem><para>Bitmapped screen fonts</para></listitem> - -</varlistentry> -</variablelist></para> - -<para>The <filename>.fot</filename> file is used by Windows as sort -of a symbolic link to the actual TrueType font -(<filename>.ttf</filename>) file. The <filename>.fon</filename> font -files are also used by Windows. I know of no way to use this font -format with FreeBSD.</para> - -</chapter> - -<chapter> -<title>What font formats can I use?</title> - -<para>Which font file format is useful depends on the application -being used. FreeBSD by itself uses no fonts. Application programs -and/or drivers may make use of the font files. Here is a small cross -reference of application/driver to the font type suffixes:</para> - -<para> -<variablelist> -<varlistentry><term>Driver</term> -<listitem> -<para> -<variablelist> -<varlistentry><term>syscons</term> -<listitem> -<para><filename>.fnt</></para> - -</listitem> -</varlistentry> -</variablelist> -</para> - -</listitem> -</varlistentry> - -<varlistentry><term>Application</term> - -<listitem> -<para> -<variablelist> -<varlistentry><term>Ghostscript</term> -<listitem> -<para><filename>.pfa</filename>, <filename>.pfb</filename>, <filename>.ttf</filename></para> - -</listitem> -</varlistentry> - -<varlistentry><term>X11</term> - -<listitem> -<para><filename>.pfa</filename>, <filename>.pfb</filename></para> - -</listitem> -</varlistentry> - -<varlistentry><term>Groff</term> - -<listitem> -<para><filename>.pfa</filename>, <filename>.afm</filename></para> - -</listitem> -</varlistentry> - -<varlistentry><term>Povray</term> - -<listitem> -<para><filename>.ttf</filename></para> - -</listitem> -</varlistentry> -</variablelist> -</para> - -</listitem> -</varlistentry> -</variablelist> -</para> - -<para>The <filename>.fnt</filename> suffix is used quite frequently. -I suspect that whenever someone wanted to create a specialized font -file for their application, more often than not they chose this -suffix. Therefore, it is likely that files with this suffix are not -all the same format; specifically, the <filename>.fnt</filename> -files used by syscons under FreeBSD may not be the same format as a -<filename>.fnt</filename> file one encounters in the MSDOS/Windows -environment. I have not made any attempt at using other -<filename>.fnt</filename> files other than those provided with -FreeBSD.</para> - -</chapter> - -<chapter> -<title>Setting a virtual console to 80x60 line mode</title> - -<para>First, a 8x8 font must be loaded. -<filename>/etc/sysconfig</filename> should contain the lines: -<informalexample> -<programlisting># Choose font 8x8 from /usr/share/syscons/fonts/* (or NO for default) -font8x8=/usr/share/syscons/fonts/cp437-8x8.fnt</programlisting> -</informalexample> -</para> - -<para>The command to actually switch the mode is -<citerefentry><refentrytitle>vidcontrol</><manvolnum>1</></>: -<informalexample> -<screen>bash$ <userinput>vidcontrol VGA_80x60</userinput></screen> -</informalexample> -</para> - -<para>Various screen orientated programs, such as -<citerefentry><refentrytitle>vi</><manvolnum>1</></>, must be able to -determine the current screen dimensions. These can be set with -<citerefentry><refentrytitle>stty</><manvolnum>1</></>: -<informalexample> -<screen>bash$ <userinput>stty crt rows 60 columns 80</userinput></screen> -</informalexample> -</para> - -<para>To make this more seamless, one can embed these commands in the -startup scripts so it takes place when the system boots. One way to -do this is: -<orderedlist> - -<listitem> -<para>Modify <filename>/etc/sysconfig</filename> as above</para> -</listitem> - -<listitem> -<para>Add to <filename>/etc/rc.local</filename>: -<informalexample> -<programlisting>for tty in /dev/ttyv? -do - vidcontrol VGA_80x60 <$tty >/dev/null 2>&1 -done</programlisting> -</informalexample></para> -</listitem> - -<listitem> -<para>Add to <filename>/etc/profile</filename>: -<informalexample> -<programlisting>TTYNAME=`basename \`tty\`` -if expr "$TTYNAME" : 'ttyv' >/dev/null -then - stty crt rows 60 columns 80 -fi</programlisting> -</informalexample> -</para> -</listitem> - -</orderedlist> -</para> - -<para>References: -<citerefentry><refentrytitle>stty</><manvolnum>1</></>, -<citerefentry><refentrytitle>vidcontrol</><manvolnum>1</></>.</para> - -</chapter> - -<chapter> -<title>Using type 1 fonts with X11</title> - -<para>X11 can use either the <filename>.pfa</filename> or the -<filename>.pfb</filename> format fonts. The X11 fonts are located in -various subdirectories under -<filename>/usr/X11R6/lib/X11/fonts</filename>. Each font file is -cross referenced to its X11 name by the contents of the -<filename>fonts.dir</filename> file in each directory.</para> - -<para>There is already a directory named <filename>Type1</>. The most -straight forward way to add a new font is to put it into this -directory. A better way is to keep all new fonts in a separate -directory and use a symbolic link to the additional font. This -allows one to more easily keep track of ones fonts without confusing -them with the fonts that were originally provided. For -example: -<informalexample> -<screen><lineannotation>Create a directory to contain the font files</> -bash$ <userinput>mkdir -p /usr/local/share/fonts/type1</> -bash$ <userinput>cd /usr/local/share/fonts/type1</> - -<lineannotation>Place the .pfa, .pfb and .afm files here</> -<lineannotation>One might want to keep readme files, and other documentation</> -<lineannotation>for the fonts here also</> -bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.pfb .</> -bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.afm .</> - -<lineannotation>Maintain an index to cross reference the fonts</> -bash$ <userinput>echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX</></screen> -</informalexample> -</para> - -<para>Now, to use a new font with X11, one must make the font file -available and update the font name files. The X11 font names look -like: -<informalexample> -<screen>-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 - | | | | | | | | | | | | \ \ - | | | | | \ \ \ \ \ \ \ +----+- character set - | | | | \ \ \ \ \ \ \ +- average width - | | | | \ \ \ \ \ \ +- spacing - | | | \ \ \ \ \ \ +- vertical res. - | | | \ \ \ \ \ +- horizontal res. - | | | \ \ \ \ +- points - | | | \ \ \ +- pixels - | | | \ \ \ - foundry family weight slant width additional style</screen> -</informalexample> -</para> - -<para>A new name needs to be created for each new font. If you have -some information from the documentation that accompanied the font, -then it could serve as the basis for creating the name. If there is -no information, then you can get some idea by using -<citerefentry><refentrytitle>strings</><manvolnum>1</></> on the font -file. For example: -<informalexample> -<screen>bash$ <userinput>strings showboat.pfb | more</> -%!FontType1-1.0: Showboat 001.001 -%%CreationDate: 1/15/91 5:16:03 PM -%%VMusage: 1024 45747 -% Generated by Fontographer 3.1 -% Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten. -FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup -/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse -{save true}{false}ifelse}{false}ifelse -12 dict begin -/FontInfo 9 dict dup begin - /version (001.001) readonly def - /FullName (Showboat) readonly def - /FamilyName (Showboat) readonly def - /Weight (Medium) readonly def - /ItalicAngle 0 def - /isFixedPitch false def - /UnderlinePosition -106 def - /UnderlineThickness 16 def - /Notice (Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def -end readonly def -/FontName /Showboat def ---stdin--</screen> -</informalexample></para> - -<para>Using this information, a possible name might be: -<informalexample> -<screen>-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1</screen> -</informalexample> -</para> - -<para>The components of our name are: -<variablelist> - -<varlistentry><term>Foundry</term> -<listitem> -<para>Lets just name all the new fonts <literal>type1</>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Family</term> -<listitem> -<para>The name of the font.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Weight</term> -<listitem> -<para>Normal, bold, medium, semibold, etc. From the -<citerefentry><refentrytitle>strings</><manvolnum>1</></> output -above, it appears that this font has a weight of -<emphasis>medium</emphasis>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Slant</term> -<listitem> -<para><emphasis remap=bf>r</emphasis>oman, <emphasis -remap=bf>i</emphasis>talic, <emphasis remap=bf>o</emphasis>blique, -etc. Since the <emphasis>ItalicAngle</emphasis> is zero, -<emphasis>roman</emphasis> will be used.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Width</term> -<listitem> -<para>Normal, wide, condensed, extended, etc. Until it can be examined, -the assumption will be <emphasis>normal</emphasis>.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Additional style</term> -<listitem> -<para>Usually omitted, but this will indicate that -the font contains decorative capital letters.</para> -</listitem> -</varlistentry> - -<varlistentry><term>Spacing</term> -<listitem> -<para>proportional or monospaced. <emphasis>Proportional</emphasis> -is used since <emphasis>isFixedPitch</emphasis> is false.</para> -</listitem> -</varlistentry> - -</variablelist> -</para> - -<para>All of these names are arbitrary, but one should strive to be -compatible with the existing conventions. A font is referenced by -name with possible wild cards by an X11 program, so the name chosen -should make some sense. One might begin by simply using -<informalexample> -<screen>…-normal-r-normal-…-p-…</screen> -</informalexample> -as the name, and then use -<citerefentry><refentrytitle>xfontsel</><manvolnum>1</></> to examine it -and adjust the name based on the appearance of the font.</para> - -<para>So, to complete our example: -<informalexample> -<screen><lineannotation>Make the font accessible to X11</> -bash$ <userinput>cd /usr/X11R6/lib/X11/fonts/Type1</> -bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</> - -<lineannotation>Edit fonts.dir and fonts.scale, adding the line describing the font -and incrementing the number of fonts which is found on the first line.</> -bash$ <userinput>ex fonts.dir -:1p -25 -:1c -26 -. -:$a -showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 -. -:wq</> - -<lineannotation><filename>fonts.scale</> seems to be identical to <filename>fonts.dir</>…</> -bash$ <userinput>cp fonts.dir fonts.scale</> - -<lineannotation>Tell X11 that things have changed</> -bash$ <userinput>xset fp rehash</> - -<lineannotation>Examine the new font</> -bash$ <userinput>xfontsel -pattern -type1-*</></screen> -</informalexample> -</para> - -<para>References: -<citerefentry><refentrytitle>xfontsel</><manvolnum>1</></>, -<citerefentry><refentrytitle>xset</><manvolnum>1</></>, -<citetitle>The X Windows System in a Nutshell</>, <ulink -URL="http://www.ora.com/">O'Reilly & Associates</ulink>.</para> - -</chapter> - -<chapter> -<title>Using type 1 fonts with Ghostscript</title> - -<para>Ghostscript references a font via its <filename>Fontmap</> -file. This must be modified in a similar way to the X11 -<filename>fonts.dir</filename> file. Ghostscript can use either the -<filename>.pfa</filename> or the <filename>.pfb</filename> format -fonts. Using the font from the previous example, here is how to use -it with Ghostscript: -<informalexample> -<screen><lineannotation>Put the font in Ghostscript's font directory</> -bash$ <userinput>cd /usr/local/share/ghostscript/fonts</> -bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</> - -<lineannotation>Edit Fontmap so Ghostscript knows about the font</> -bash$ <userinput>cd /usr/local/share/ghostscript/4.01</> -bash$ <userinput>ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq</> - -<lineannotation>Use Ghostscript to examine the font</> -bash$ <userinput>gs prfont.ps</> -Aladdin Ghostscript 4.01 (1996-7-10) -Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights -reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... - /1899520 581354 1300084 13826 0 done. -GS><userinput>Showboat DoFont</> -Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... - 1939688 565415 1300084 16901 0 done. ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< -GS><userinput>quit</></screen> -</informalexample> -</para> - -<para>References: <filename>fonts.txt</filename> in the Ghostscript -4.01 distribution</para> - -</chapter> - -<chapter> -<title>Using type 1 fonts with Groff</title> - -<para>Now that the new font can be used by both X11 and Ghostscript, -how can one use the new font with groff? First of all, since we are -dealing with type 1 postscript fonts, the groff device that is -applicable is the <emphasis>ps</emphasis> device. A font file must be -created for each font that groff can use. A groff font name is just -a file in <filename>/usr/share/groff_font/devps</filename>. With our -example, the font file could be -<filename>/usr/share/groff_font/devps/SHOWBOAT</filename>. The file -must be created using tools provided by groff.</para> - -<para>The first tool is <command>afmtodit</>. This is not normally -installed, so it must be retrieved from the source distribution. I -found I had to change the first line of the file, so I did: -<informalexample> -<screen>bash$ <userinput>cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp</> -bash$ <userinput>ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq</></screen> -</informalexample> -</para> - -<para>This tool will create the groff font file from the metrics file -(<filename>.afm</filename> suffix.) Continuing with our -example: -<informalexample> -<screen><lineannotation>Many <filename>.afm</> files are in Mac format&hellip ^M delimited lines -We need to convert them to unix style ^J delimited lines</> -bash$ <userinput>cd /tmp</> -bash$ <userinput>cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm</> - -<lineannotation>Now create the groff font file</> -bash$ <userinput>cd /usr/share/groff_font/devps</> -bash$ <userinput>/tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT</></screen> -</informalexample> -</para> - -<para>The font can now be referenced with the name SHOWBOAT.</para> - -<para>If ghostscript is used to drive the printers on the system, -then nothing more needs to be done. However, if true postscript -printers are used, then the font must be down loaded to the printer -in order for the font to be used (unless the printer happens to have -the showboat font built in or on an accessible font disk.) The final -step is to create a down loadable font. The <command>pfbtops</> tool -is used to create the <filename>.pfa</filename> format of the font, -and the <filename>download</> file is modified to reference the new -font. The <filename>download</> file must reference the internal -name of the font. This can easily be determined from the groff font -file as illustrated: -<informalexample> -<screen><lineannotation>Create the <filename>.pfa</> font file</> -bash$ <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa</></screen> -</informalexample> -Of course, if the <filename>.pfa</filename> file is already -available, just use a symbolic link to reference it. -<informalexample> -<screen><lineannotation>Get the internal font name</> -bash$ <userinput>fgrep internalname SHOWBOAT</> -internalname Showboat - -<lineannotation>Tell groff that the font must be down loaded</> -bash$ <userinput>ex download -:$a -Showboat showboat.pfa -. -:wq</></screen> -</informalexample> -</para> - -<para>To test the font: -<informalexample> -<screen>bash$ <userinput>cd /tmp</> -bash$ <userinput>cat >example.t <<EOF -.sp 5 -.ps 16 -This is an example of the Showboat font: -.br -.ps 48 -.vs (\n(.s+2)p -.sp -.ft SHOWBOAT -ABCDEFGHI -.br -JKLMNOPQR -.br -STUVWXYZ -.sp -.ps 16 -.vs (\n(.s+2)p -.fp 5 SHOWBOAT -.ft R -To use it for the first letter of a paragraph, it will look like: -.sp 50p -\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the -showboat font as its first letter. -Additional vertical space must be used to allow room for the larger -letter. -EOF</> -bash$ <userinput>groff -Tps example.t >example.ps</> - -<lineannotation>To use ghostscript/ghostview</> -bash$ <userinput>ghostview example.ps</> - -<lineannotation>To print it</> -bash$ <userinput>lpr -Ppostscript example.ps</></screen> -</informalexample> -</para> - -<para>References: -<filename>/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man</filename>, -<citerefentry><refentrytitle>groff_font</><manvolnum>5</></>, -<citerefentry><refentrytitle>groff_char</><manvolnum>5</></>, -<citerefentry><refentrytitle>pfbtops</><manvolnum>1</></>.</para> - -</chapter> - - <chapter> - <title>Converting TrueType fonts to a groff/postscript format for - groff</title> - - <para>This potentially requires a bit of work, simply because it - depends on some utilities that are not installed as part of the - base system. They are:</para> - - <variablelist> - <varlistentry> - <term><command>ttf2pf</command></term> - - <listitem> - <para>TrueType to postscript convertsion utilities. This - allows conversion of a TrueType font to an ascii font - metric (<filename>.afm</filename>) file.</para> - - <para>Currently available at <ulink - url="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/">http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf</ulink>. - Note: These files are postscript programs and must be - downloaded to disk by holding down the - <keycap>Shift</keycap> key when clicking on the - link. Otherwise, your browser may try to launch - <application>ghostview</application> to view them.</para> - - <para>The files of interest are:</para> - - <itemizedlist> - <listitem> - <para><filename>GS_TTF.PS</filename></para - </listitem> - - <listitem> - <para><filename>PF2AFM.PS</filename></para> - </listitem> - - <listitem> - <para><filename>ttf2pf.ps</filename></para> - </listitem> - </itemizedlist> - - <para>The funny upper/lower case is due to their being - intended also for DOS shells. - <filename>ttf2pf.ps</filename> makes use of the others as - upper case, so any renaming must be consistent with - this. (Actually, <filename>GS_TTF.PS</filename> and - <filename>PFS2AFM.PS</filename> are supposedly part of the - ghostscript distribution, but it's just as easy to use - these as an isolated utility. FreeBSD doesn't seem to - include the latter.) You also may want to have these - installed to - <filename>/usr/local/share/groff_font/devps</filename>(?).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>afmtodit</command></term> - - <listitem> - <para>Creates font files for use with groff from ascii font - metrics file. This usually resides in the directory, - <filename>/usr/src/contrib/groff/afmtodit</filename>, and - requires some work to get going.</para> - - <note> - <para> If you're paranoid about working in the - <filename>/usr/src</filename> tree, simply copy the - contents of the above directory to a work - location.</para> - </note> - - <para>In the work area, you'll need to make the - utility. Just type:</para> - - <screen> -<prompt>#</prompt> <userinput>make -f Makefile.sub afmtodit</userinput> - </screen> - - <para>You may also need to copy - <filename>/usr/contrib/groff/devps/generate/textmap</filename> - to - <filename>/usr/share/groff_font/devps/generate</filename> - if it doesn't already exist.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Once all these utilities are in place, you're ready to - commence:</para> - - <orderedlist> - <listitem> - <para>Create the <filename>.afm</filename> file by - typing:</para> - - <screen> -<prompt>%</prompt> <userinput>gs <optional>-dNODISPLAY</optional> <optional>-q</optional> -- ttf2pf.ps <replaceable>TTF_name</replaceable> <optional><replaceable>PS_font_name</replaceable> <optional><replaceable>AFM_name</replaceable></optional></optional></userinput> - </screen> - - <para>Where, <replaceable>TTF_name</replaceable> is your - TrueType font file, <replaceable>PS_font_name</replaceable> - is the file name for the <filename>.pfa</filename> file, - <replaceable>AFM_name</replaceable> is the name you wish for - the <filename>.afm</filename> file. If you do not specify - output file names for the <filename>.pfa</filename> or - <filename>.afm</filename> files, then default names will be - generated from the TrueType font file name.</para> - - <para>This also produces a <filename>.pfa</filename> file, the - ascii postscript font metrics file - (<filename>.pfb</filename> is for the binrary form). This - won't be needed, but could (I think) be useful for a - fontserver.</para> - - <para>For example, to convert the 30f9 Barcode font using the - default file names, use the following command:</para> - - <screen> -<prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf</userinput> -Aladdin Ghostscript 5.10 (1997-11-23) -Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Converting 3of9.ttf to 3of9.pfa and 3of9.afm. - </screen> - - <para>If you want the converted fonts to be stored in - <filename>A.pfa</filename> and <filename>B.afm</filename>, - then use this command:</para> - - <screen> -<prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B</userinput> -Aladdin Ghostscript 5.10 (1997-11-23) -Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Converting 3of9.ttf to A.pfa and B.afm. - </screen> - </listitem> - - <listitem> - <para>Create the groff postscript file:</para> - - <para>Change directories to - <filename>/usr/share/groff_font/devps</filename> so as to - make the following command easier to execute. You'll - probably need root priviledges for this. (Or, if you're - paranoid about working there, make sure you reference the - files <filename>DESC</filename>, - <filename>text.enc</filename> and - <filename>generate/textmap</filename> as being in this - directory.)</para> - - <screen> -<prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc file.afm \ - generate/textmap <replaceable>PS_font_name</replaceable></userinput> - </screen> - - <para>Where, <filename>file.afm</filename> is the - <replaceable>AFM_name</replaceable> created by - <command>ttf2pf.ps</command> above, and - <replaceable>PS_font_name</replaceable> is the font name - used from that command, as well as the name that - <citerefentry> <refentrytitle>groff</><manvolnum>1</></> - will use for references to this font. For example, assuming - you used the first <command>tiff2pf.ps</command> command - above, then the 3of9 Barcode font can be created using the - command:</para> - - <screen> -<prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc 3of9.afm \ - generate/textmap 3of9</userinput> - </screen> - - <para>Ensure that the resulting - <replaceable>PS_font_name</replaceable> file (e.g., - <filename>3of9</filename> in the example above) is located - in the directory - <filename>/usr/share/groff_font/devps</filename> by copying - or moving it there.</para> - - <para>Note that if <filename>ttf2pf.ps</filename> assigns a - font name using the one it finds in the TrueType font file - and you want to use a different name, you must edit the - <filename>.afm</filename> file prior to running - <command>afmtodit</command>. This name must also match the - one used in the Fontmap file if you wish to pipe - <citerefentry><refentrytitle>groff</><manvolnum>1</></> into - <citerefentry><refentrytitle>gs</><manvolnum>1</></>.</para> - </listitem> - </orderedlist> - </chapter> - -<chapter> -<title>Can TrueType fonts be used with other programs?</title> - -<para>The TrueType font format is used by Windows, Windows 95, and -Mac's. It is quite popular and there are a great number of -fonts available in this format.</para> - -<para>Unfortunately, there are few applications that I am aware of -that can use this format: Ghostscript and Povray come to mind. -Ghostscript's support, according to the documentation, is rudimentary -and the results are likely to be inferior to type 1 fonts. -Povray version 3 also has the ability to use TrueType fonts, but -I rather doubt many people will be creating documents as a series of -raytraced pages :-).</para> - -<para>This rather dismal situation may soon change. -The <ulink url="http://www.freetype.org/">FreeType Project</ulink> -is currently developing a useful set of FreeType tools: -<itemizedlist> -<listitem> -<simpara>The <command>xfsft</command> font server for X11 can serve -TrueType fonts in addition to regular fonts. Though currently in -beta, it is said to be quite useable. See <ulink -url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz -Chroboczek's page</ulink> for further information. Porting instructions -for FreeBSD can be found at <ulink -url="http://math.missouri.edu/~stephen/software/">Stephen Montgomery's -software page</ulink>. -</simpara> -</listitem> -<listitem> -<simpara><command>xfstt</command> is another font -server for X11, available under <ulink -url=" ftp://sunsite.unc.edu/pub/Linux/X11/fonts"> -ftp://sunsite.unc.edu/pub/Linux/X11/fonts</ulink>. -</simpara> -</listitem> -<listitem><simpara>A program called <command>ttf2bdf</command> can produce -BDF files suitable for use in an X environment from TrueType files. Linux -binaries are said to be available from <ulink -url="ftp://crl.nmsu.edu/CLR/multiling/General">ftp://crl.nmsu.edu/CLR/multiling/General/</ulink>. -</simpara> -</listitem> -<listitem> -<simpara> -For people requiring the use of Asian TrueType fonts, the -<command>XTT</command> font server may be worth a look. Information about -<command>XTT</command> can be found at URL: <ulink -url="http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html">http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html</ulink>. -</simpara> -</listitem> -<listitem> -<simpara>and others …</simpara> -</listitem> -</itemizedlist> -</para> -<para> -The -<ulink url="http://www.freetype.org/projects.htm">FreeType Projects page -</ulink> is a good starting point for information on these and other -free TrueType projects. -</para> -</chapter> - -<chapter> -<title>Where can additional fonts be obtained?</title> - -<para>Many fonts are available on the Internet. They are either -entirely free, or are share-ware. In addition, there are many -inexpensive CDROMs available that contain many fonts. Some Internet -locations (as of August 1996) are: -<itemizedlist> - -<listitem><para><ulink -url="ftp://ftp.winsite.com">ftp://ftp.winsite.com</ulink> (Formerly -CICA)</para></listitem> - -<listitem><para><ulink -url="http://www.simtel.net/simcgi-bin/dosfind.cgi">http://www.simtel.net/simcgi-bin/dosfind.cgi</ulink></para></listitem> - -<listitem><para><ulink -url="ftp://ftp.coast.net/">ftp://ftp.coast.net/</ulink></para></listitem> - -<listitem><para><ulink -url="http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html">http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html</ulink></para></listitem> - -<listitem><para><ulink -url="http://www.esselte.com/letraset/index.html">http://www.esselte.com/letraset/index.html</ulink></para></listitem> - -<listitem><para><ulink -url="http://www.inil.com/users/elfring/esf.htm">http://www.inil.com/users/elfring/esf.htm</ulink></para></listitem> - -</itemizedlist></para> - -</chapter> - -<chapter> -<title>Additional questions</title> - -<para> -<itemizedlist> - -<listitem> -<para>What use are the <filename>.pfm</filename> files?</para> -</listitem> - -<listitem> -<para>Can one generate the <filename>.afm</filename> file from a <filename>.pfa</filename> or <filename>.pfb</filename>?</para> -</listitem> - -<listitem> -<para>How to generate the groff character mapping files for postscript fonts -with non-standard character names?</para> -</listitem> - -<listitem> -<para>Can xditview and devX?? devices be setup to access all the new fonts?</para> -</listitem> - -<listitem> -<para>It would be good to have examples of using TrueType fonts with povray and -ghostscript.</para> -</listitem> - -</itemizedlist> -</para> - -</chapter> -</book> diff --git a/en/tutorials/index.sgml b/en/tutorials/index.sgml deleted file mode 100644 index 6ee885bbf2..0000000000 --- a/en/tutorials/index.sgml +++ /dev/null @@ -1,58 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [ -<!ENTITY base CDATA ".."> -<!ENTITY date "$Date: 1999-04-26 21:50:42 $"> -<!ENTITY title "FreeBSD Tutorials"> -<!ENTITY % includes SYSTEM "../includes.sgml"> %includes; -]> -<!-- $Id: index.sgml,v 1.20 1999-04-26 21:50:42 nik Exp $ --> - -<html> -&header; - - <p>Here lie assorted documents on various aspects of FreeBSD, - FreeBSD software, and hardware. If you have comments or - would like to contribute a document, please contact us at - <a href="mailto:freebsd-doc@FreeBSD.ORG">freebsd-doc@FreeBSD.org</a>.</p> - - <ul> - <li><a href="newuser/newuser.html">For People New to Both FreeBSD - <em>and</em> Unix</a></li> - - <li><a href="mh/mh.html">An introduction to the MH mail software</a></li> - - <li><a href="devel/devel.html">A User's Guide to FreeBSD Programming - Tools</a></li> - - <li><a href="ddwg/ddwg.html">Writing device drivers for FreeBSD</a> - (<a href="ddwg/ddwg.ps">postscript</a>, - <a href="ddwg/ddwg-html.tar.gz">gzipd tar file</a>)</li> - - <li><a href="ppp/ppp.html">Pedantic PPP primer - IP Aliasing</a> - (<a href="ppp/ppp.ps">postscript</a>, - <a href="ppp/ppp-html.tar.gz">gzipd tar file</a>)</li> - - <li><a href="multios/multios.html">Using FreeBSD with other operating systems</a></li> - - <li><a href="fonts/fonts.html">Fonts and FreeBSD</a></li> - - <li><a href="http://www.cypher.net/~black/ipalias.html">IP Aliasing</a></li> - <li><a href="http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html">Upgrading FreeBSD from source (using <b><tt>make world</tt></b>)</a></li> - <li><a href="diskformat/diskformat.html">Formatting Media For Use With FreeBSD -2.2-RELEASE</a></li> - - <li><a href="http://www.users.globalnet.co.uk/~markov/ntfs_install.html">Installing the FreeBSD NTFS (NT Filesystem) driver</a></li> - - <li><a href="http://www.freebsd.org/~rpratt/227/">FreeBSD 2.2.7 Installation Details for Newbies</a> - - <li><a href="&base;/tutorials/docproj-primer/">FreeBSD Documentation - Project Primer</a> (many small HTML files)</li> - - <li><a href="&base;/tutorials/docproj-primer/book.html">FreeBSD - Documentation Project Primer</a> (one large HTML file)</li> - </ul> - - -&footer; -</body> -</html> - diff --git a/en/tutorials/mh/Makefile b/en/tutorials/mh/Makefile deleted file mode 100644 index 14a686e6af..0000000000 --- a/en/tutorials/mh/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $ - -DOCS= mh.docb -INDEXLINK= mh.html - -.include "../../web.mk" - diff --git a/en/tutorials/mh/mh.docb b/en/tutorials/mh/mh.docb deleted file mode 100644 index 839f8b7611..0000000000 --- a/en/tutorials/mh/mh.docb +++ /dev/null @@ -1,704 +0,0 @@ -<!-- $Id: mh.docb,v 1.2 1997-07-01 21:38:44 max Exp $ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> - -<bookinfo> -<bookbiblio> -<title>An MH Primer</title> - -<authorgroup> -<author> -<firstname>Matt</firstname> -<surname>Midboe</surname> -<affiliation> -<address> -<email>matt@garply.com</email> -</address> -</affiliation> -</author></authorgroup> - -<pubdate>v1.0, 16 January 1996</pubdate> - -<abstract><para>This document contains an introduction to using MH on -FreeBSD</para></abstract> - -</bookbiblio> -</bookinfo> - -<chapter id="mhintro"> -<title>Introduction</title> - -<para>MH started back in 1977 at the RAND Corporation, where the -initial philosophies behind MH were developed. MH isn't so much a -monolithic email program but a philosophy about how best to develop -tools for reading email. The MH developers have done a great job -adhering to the <acronym>KISS</> principle: Keep It Simple Stupid. -Rather than have one large program for reading, sending and handling -email they have written specialized programs for each part of your -email life. One might liken MH to the specialization that one finds -in insects and nature. Each tool in MH does one thing, and does it -very well.</para> - -<para>Beyond just the various tools that one uses to handle their -email MH has done an excellent job keeping the configuration of each -of these tools consistent and uniform. In fact, if you are not quite -sure how something is supposed to work or what the arguments for some -command are supposed to be then you can generally guess and be right. -Each MH command is consistent about how it handles reading the -configuration files and how it takes arguments on the command line. -One useful thing to remember is that you can always add a -<option>-help</option> to the command to have it display the options -for that command.</para> - -<para>The first thing that you need to do is to make sure that you have -installed the MH package on your FreeBSD machine. If you installed -from CDROM you should be able to execute the following to load mh: -<informalexample> -<screen># <userinput>pkg_add /cdrom/packages/mh-6.8.3.tgz</></screen> -</informalexample> -You will notice that it created a <filename>/usr/local/lib/mh</> -directory for you as well as adding several binaries to the -<filename>/usr/local/bin</> directory. If you would prefer to compile -it yourself then you can anonymous ftp it from <ulink -URL="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink -URL="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para> - -<para>This primer is not a full comprehensive explanation of how MH -works. This is just intended to get you started on the road to -happier, faster mail reading. You should read the man pages for the -various commands. Also you might want to read the <ulink -URL="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also you can -read the <ulink -URL="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mh-faq/part1/faq.html">FAQ -for MH</ulink>. The best resource for MH is the O'Reilly and Associates book -written by Jerry Peek.</para> - -</chapter> - -<chapter> -<title>Reading Mail</title> - -<para>This section covers how to use <command>inc</>, -<command>show</>, <command>scan</>, <command>next</>, -<command>prev</>, <command>rmm</>, <command>rmf</>, and -<command>msgchk</>. One of the best things about MH is the -consistent interface between programs. A few things to keep in mind -when using these commands is how to specify message lists. In the -case of <command>inc</> this doesn't really make any sense but with -commands like <command>show</> it is useful to know. </para> - -<para>A message list can consist of something like <parameter>23 20 -16</> which will act on messages 23, 20 and 16. This is fairly simple -but you can do more useful things like <parameter>23-30</> which will -act on all the messages between 23 and 30. You can also specify -something like <parameter>cur:10</> which will act on the current -message and the next 9 messages. The <parameter>cur</>, -<parameter>last</>, and <parameter>first</> messages are special -messages that refer to the current, last or first message in the -folder.</para> - - -<sect1 id="inc"> -<title><command>inc</>, <command>msgchk</>—read in your new email or check it</title> - -<para>If you just type in <userinput>inc</> and hit <keycap>return</> -you will be well on your way to getting started with MH. The first -time you run <command>inc</> it will setup your account to use all -the MH defaults and ask you about creating a Mail directory. If you -have mail waiting to be downloaded you will see something that looks -like: -<informalexample> -<screen> 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J - 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa</screen> -</informalexample> -This is the same thing you will see from a <command>scan</> (see -<xref linkend="scan">). If you just run <command>inc</> with no -arguments it will look on your computer for email that is supposed to -be coming to you.</para> - -<para>A lot of people like to use POP for grabbing their email. MH can do -POP to grab your email. You will need to give <command>inc</> a few command -line arguments. -<informalexample> -<screen>tempest% <userinput>inc -host mail.pop.org -user <replaceable>username</> -norpop</></screen> -</informalexample> -That tells <command>inc</> to go to <parameter>mail.pop.org</> to -download your email, and that your username on their system is -<replaceable>username</>. The <option>-norpop</option> option tells -<command>inc</> to use plain POP3 for downloading your email. MH has -support for a few different dialects of POP. More than likely you -will never ever need to use them though. While you can do more -complex things with inc such as audit files and scan format files -this will get you going.</para> - -<para>The <command>msgchk</> command is used to get information on -whether or not you have new email. <command>msgchk</> takes the same -<option>-host</option> and <option>-user</option> options that -<command>inc</> takes.</para> - -</sect1> - -<sect1 id="show"> -<title><command>show</>, <command>next</> and <command>prev</>—displaying and moving through email</title> - -<para><command>show</> is to show a letter in your current folder. -Like <command>inc</>, <command>show</> is a fairly straightforward -command. If you just type <userinput>show</> and hit <keycap>return</> -then it displays the current message. You can also give specific -message numbers to show: -<informalexample> -<screen>tempest% <userinput>show 32 45 56</></screen> -</informalexample> -This would display message numbers 32, 45 and 56 right after each -other. Unless you change the default behavior <command>show</> -basically just does a <command>more</> on the email message.</para> - -<para><command>next</> is used to move onto the next message and -<command>prev</> will go to the previous message. Both commands have -an implied <command>show</> command so that when you go to the next -message it automatically displays it.</para> - -</sect1> - -<sect1 id="scan"> -<title><command>scan</>—shows you a scan of your messages</title> - -<para><command>scan</> will display a brief listing of the messages -in your current folder. This is an example of what the -<command>scan</> command will give you. -<informalexample> -<screen> 30+ 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa</screen> -</informalexample> -Like just about everything in MH this display is very configurable. -This is the typical default display. It gives you the message number, -the date on the email, the sender, the subject line, and a sentence -fragment from the very beginning of the email if it can fit it. The -<literal>+</> means that message is the current message, so if you do -a <command>show</> it will display that message.</para> - -<para>One useful option for scan is the <option>-reverse</option> -option. This will list your messages with the highest message number -first and lowest message number last. Another useful option with -<command>scan</> is to have it read from a file. If you want to scan -your incoming mailbox on FreeBSD without having to <command>inc</> it -you can do <command>scan -file -/var/mail/<replaceable>username</></command>. This can be used with -any file that is in the <database>mbox</> format.</para> - -</sect1> - -<sect1 id="rmm"> -<title><command>rmm</> and <command>rmf</>—remove the current message or folder</title> - -<para><command>rmm</> is used to remove a mail message. The default -is typically to not actually remove the message but to rename the -file to one that is ignored by the MH commands. You will need to -through periodically and physically delete the <quote>removed</> -messages.</para> - -<para>The <command>rmf</> command is used to remove folders. This -doesn't just rename the files but actually removes the from the hard -drive so you should be careful when you use this command.</para> - -</sect1> - -<sect1 id="samplereading"> -<title>A typical session of reading with MH</title> - -<para>The first thing that you will want to do is <command>inc</> -your new mail. So at a shell prompt just type in <command>inc</> and -hit <keycap>return</>. -<informalexample> -<screen>tempest% <userinput>inc</> -Incorporating new mail into inbox... - - 36+ 01/19 "Stephen L. Lange Request...<<Please remove me as contact for pind - 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest%</screen> -</informalexample> -This shows you the new email that has been added to your mailbox. So -the next thing to do is <command>show</> the email and move around. -<informalexample> -<screen>tempest% <userinput>show</> -Received: by sashimi.wwa.com (Smail3.1.29.1 #2) - id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST -Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) -From: "Stephen L. Lange" <stvlange@wwa.com> -To: matt@garply.com -Subject: Request... -Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII - - -Please remove me as contact for pindat.com - -tempest% <userinput>rmm</> -tempest% <userinput>next</> -Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 -.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT -Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> -X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro -tocol -To: hsu@clinet.fi -Cc: hackers@FreeBSD.org -Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet - boards) -In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." - <199601182318.AA11772@Sysiphos> -X-Mailer: exmh version 1.5omega 10/6/94 -Date: Fri, 19 Jan 1996 17:56:40 +0000 -From: Matt Thomas <matt@lkg.dec.com> -Sender: owner-hackers@FreeBSD.org -Precedence: bulk - - -This is due to a typo in pcireg.h (to -which I am probably the guilty party).</screen> -</informalexample></para> - -<para>The <command>rmm</> removed the current message and the -<command>next</> command moved me on to the next message. -Now if I wanted to look at ten most recent messages so I could read -one of them here is what I would do: -<informalexample> -<screen>tempest% <userinput>scan last:10</> - 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has - 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 - 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue - 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki - 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< - 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 - 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan - 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne - 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -tempest%</screen> -</informalexample> -Then if I wanted to read message number 27 I would do a -<userinput>show 27</> and it would be displayed. As you can probably -tell from this sample session MH is pretty easy to use and looking -through emails and displaying them is fairly intuitive and easy. -</para> - -</sect1> -</chapter> - -<chapter> -<title>Folders and Mail Searching</title> - -<para>Anybody who gets lots of email definitely wants to be able to -prioritize, stamp, brief, de-brief, and number their emails in a -variety of different ways. MH can do this better than just about -anything. One thing that we haven't really talked about is the -concept of folders. You have undoubtedly come across the folders -concept using other email programs. MH has folders too. MH can even -do sub-folders of a folder. One thing you should keep in mind with MH -is that when you ran <command>inc</> for the first time and it asked -you if it could create a <filename>Mail</> directory it began storing -everything in that directory. If you look at that directory you will -find a directory named <filename>inbox</>. The <filename>inbox</> -directory houses all of your incoming mail that hasn't been thrown -anywhere else.</para> - -<para>Whenever you create a new folder a new directory is going to be -created underneath your MH <filename>Mail</> directory, and messages -in that folder are going to be stored in that directory. When new -email comes in that new email is thrown into your <filename>inbox</> -directory with a file name that is equivalent to the message number. -So even if you didn't have any of the MH tools to read your email you -could still use standard UNIX commands to munge around in those -directories and just more your files. It's this simplicity that -really gives you a lot of power with what you can do with your -email.</para> - -<para>Just as you can use message lists like <parameter>23 16 42</> -with most MH commands there is a folder option you can specify with -just about every MH command. If you do a <command>scan +freebsd</> it -will scan your <filename>freebsd</> folder, and your current folder -will be changed to <filename>freebsd</>. If you do a <command>show -+freebsd 23 16 42</>, <command>show</> is going to switch to your -<filename>freebsd</> folder and display messages 23, 16 and 42. So -remember that <option>+<replaceable>folder</></> syntax. You will -need to make sure you use it to make commands process different -folders. Remember you default folder for mail is <filename>inbox</> -so doing a <command>folder +inbox</> should always get you back to -your mail. Of course, in MH's infinite flexibility this can be -changed but most places have probably left it as -<command>inbox</>.</para> - - -<sect1> -<title><command>pick</>—search email that matches certain criteria</title> - -<para><command>pick</> is one of the more complex commands in the MH -system. So you might want to read the -<citerefentry><refentrytitle>pick</><manvolnum>1</></> man page for a -more thorough understanding. At its simplest level you can do -something like -<informalexample> -<screen>tempest% <userinput>pick -search pci</> -15 -42 -55 -56 -57</screen> -</informalexample> - -This will tell <command>pick</> to look through every single line in -every message in your current folder and tell you which message -numbers it found the word <literal>pci</> in. You can then -<command>show</> those messages and read them if you wish or -<command>rmm</> them. You would have to specify something like -<command>show 15 42 55-57</> to display them though. A slightly more -useful thing to do is this: -<informalexample> -<screen>tempest% <userinput>pick -search pci -seq pick</> -5 hits -tempest% <userinput>show pick</></screen> -</informalexample> -This will show you the same messages you just didn't have to work as -hard to do it. The <option>-seq</option> option is really an -abbreviation of <option>-sequence</option> and <command>pick</> is -just a sequence which contains the message numbers that matched. You -can use sequences with just about any MH command. So you could have -done an <command>rmm pick</> and all those messages would be removed -instead. You sequence can be named anything. If you run pick again it -will overwrite the old sequence if you use the same name.</para> - -<para>Doing a <command>pick -search</command> can be a bit more time -consuming than just searching for message from someone, or to -someone. So <command>pick</> allows you to use the following -predefined search criteria: - -<variablelist> - -<varlistentry> -<term><option>-to</option></term> -<listitem> -<para>search based upon who the message is to</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>-cc</option></term> -<listitem> -<para>search based on who is in the cc list</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>-from</option></term> -<listitem> -<para>search for who sent the message</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>-subject</option></term> -<listitem> -<para>search for emails with this subject</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>-date</option></term> -<listitem> -<para>find emails with a matching dat</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><option>--<replaceable>component</replaceable></option></term> -<listitem> -<para>search for any other component in the header. (i.e. -<option>--reply-to</> to find all emails with a certain reply-to in -the header)</para> -</listitem> -</varlistentry> - -</variablelist></para> - -<para>This allows you to do things like -<informalexample> -<screen>tempest% <userinput>pick -to freebsd-hackers@freebsd.org -seq hackers</></screen> -</informalexample> -to get a list of all the email send to the FreeBSD hackers mailing -list. <command>pick</> also allows you to group these criteria in -different ways using the following options: -<itemizedlist> - -<listitem> -<para>… <option>-and</option> …</para> -</listitem> - -<listitem> -<para>… <option>-or</option> &hellip</para> -</listitem> - -<listitem> -<para><option>-not</option> …</para> -</listitem> - -<listitem> -<para><option>-lbrace</option> … <option>-rbrace</option></para> -</listitem> - -</itemizedlist> -These commands allow you to do things like -<informalexample> -<screen>tempest% <userinput>pick -to freebsd-hackers -and -cc freebsd-hackers</></screen> -</informalexample> -That will grab all the email in your inbox that was sent to -freebsd-hackers or cc'd to that list. The brace options allow you to -group search criteria together. This is sometimes very necessary as -in the following example -<informalexample> -<screen>tempest% <userinput>pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci</></screen> -</informalexample></para> - -<para>Basically this says <quote>pick (to freebsd-hackers and not cc'd on -freebsd-questions) and the subject is pci</quote>. It should look through your -folder and find all messages sent to the freebsd-hackers list that -aren't cc'd to the freebsd-questions list that contain something on -pci in the subject line. Ordinarily you might have to worry about -something called operator precedence. Remember in math how you -evaluate from left to right and you do multiplication and division -first and addition and subtraction second? MH has the same type of -rules for <command>pick</>. It's fairly complex so you might want to study -the man page. This document is just to help you get acquainted with -MH.</para> - -</sect1> - -<sect1> -<title><command>folder</>, <command>folders</>, <command>refile</>—three useful programs for folder maintenance</title> - -<para>There are three programs which are primarily just for -manipulating your folders. The <command>folder</> program is used to -switch between folders, pack them, and list them. At its simplest -level you can do a <command>folder +<replaceable>newfolder</></> and -you will be switched into <replaceable>newfolder</>. From there on -out all your MH commands like <command>comp</>, <command>repl</>, -<command>scan</>, and <command>show</> will act on that -<command>newfolder</> folder.</para> - -<para>Sometimes when you are reading and deleting messages you will -develop <quote>holes</> in your folders. If you do a <command>scan</> -you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do -a <command>folder -pack</command> this will renumber all your -messages so that there are no holes. It doesn't actually delete any -messages though. So you may need to periodically go through and -physically delete <command>rmm</>'d messages.</para> - -<para>If you need statistics on your folders you can do a -<command>folders</> or <command>folder -all</command> to list all -your folders, how many messages they have, what the current message -is in each one and so on. This line of stats it displays for all your -folders is the same one you get when you change to a folder with -<command>folder +foldername</>. A <command>folders</> command looks -like this: -<informalexample> -<screen> Folder # of messages ( range ); cur msg (other files) - announce has 1 message ( 1- 1). - drafts has no messages. - f-hackers has 43 messages ( 1- 43). - f-questions has 16 messages ( 1- 16). - inbox+ has 35 messages ( 1- 38); cur= 37. - lists has 8 messages ( 1- 8). - netfuture has 1 message ( 1- 1). - out has 31 messages ( 1- 31). - personal has 6 messages ( 1- 6). - todo has 58 messages ( 1- 58); cur= 1. - - TOTAL= 199 messages in 13 folders. -</screen> -</informalexample></para> - -<para>The <command>refile</> command is what you use to move messages -between folders. When you do something like <command>refile 23 -+netfuture</> message number 23 is moved into the -<filename>netfuture</> folder. You could also do something like -<command>refile 23 +netfuture/latest</> which would put message -number 23 in a subfolder called <filename>latest</> under the -<filename>netfuture</> folder. If you want to keep a message in the -current folder and link it you can do a <command>refile -link 23 -+netfuture</command> which would keep 23 in your current -<filename>inbox</> but also list in your <filename>netfuture</> -folder. You are probably beginning to realize some of the really -powerful things you can do with MH.</para> - -</sect1> -</chapter> - -<chapter> -<title>Sending Mail</title> - -<para>Email is a two way street for most people so you want to be -able to send something back. The way MH handles sending mail can be a -bit difficult to follow at first, but it allows for incredible -flexibility. The first thing MH does is to copy a components file -into your outgoing email. A components file is basically a skeleton -email letter with stuff like the To: and Subject: headers already in -it. You are then sent into your editor where you fill in the header -information and then type the body of your message below the dashed -lines in the message. Then to the <command>whatnow</> program. When -you are at the <prompt>What now?</prompt> prompt you can tell it to -<command>send</>, <command>list</>, <command>edit</>, -<command>edit</>, <command>push</>, and <command>quit</>. Most of -these commands are self-explanatory. So the message sending process -involves copying a component file, editing your email, and then -telling the <command>whatnow</> program what to do with your -email.</para> - - -<sect1> -<title><command>comp</>, <command>forw</>, <command>reply</>—compose, forward or reply to a message to someone</title> - -<para>The <command>comp</> program has a few useful command line -options. The most important one to know right now is the -<option>-editor</option> option. When MH is installed the default -editor is usually a program called <command>prompter</> which comes -with MH. It's not a very exciting editor and basically just gets the -job done. So when you go to compose a message to someone you might -want to use <command>comp -editor /usr/bin/vi/</> or <command>comp --editor /usr/local/bin/pico/</> instead. Once you have run -<emphasis>comp</emphasis> you are in your editor and you see -something that looks like this: -<informalexample> -<screen>To: -cc: -Subject: --------- -</screen> -</informalexample></para> - -<para>You need to put the person you are sending the mail to after the -<literal>To:</> line. It works the same way for the other headers -also, so you would need to put your subject after the -<literal>Subject:</> line. Then you would just put the body of your -message after the dashed lines. It may seem a bit simplistic since a -lot of email programs have special requesters that ask you for this -information but there really isn't any point to that. Plus this -really gives you excellent flexibility. -<informalexample> -<screen>To:<userinput>freebsd-rave@freebsd.org</> -cc: -Subject:<userinput>And on the 8th day God created the FreeBSD core team</> --------- -<userinput>Wow this is an amazing operating system. Thanks!</></screen> -</informalexample> -You can now save this message and exit your editor. You will see the -<prompt>What now?</> prompt and you can type in -<userinput>send</> or <userinput>s</> and hit -<keycap>return</>. Then the freebsd core team will receive their just -rewards. As I mentioned earlier you can also use other commands, for -example <command>quit</> if you don't want to send the -message.</para> - -<para>The <command>forw</> command is stunningly similar. The big -difference being that the message you are forwarding is automatically -included in the outgoing message. When you run <command>forw</> it -will forward your current message. You can always tell it to forward -something else by doing something like <command>forw 23</> and then -message number 23 will be put in your outgoing message instead of the -current message. Beyond those small differences <command>forw</> -functions exactly the same as <command>comp</>. You go through the -exact same message sending process.</para> - -<para>The <command>repl</> command will reply to whatever your -current message is, unless you give it a different message to reply -to. <command>repl</> will do its best to go ahead and fill in some of -the email headers already. So you will notice that the -<literal>To:</> header already has the address of the recipient in -there. Also the <literal>Subject:</> line will already be filled in. -You then go about the normal message composition process and you are -done. One useful command line option to know here is the -<option>-cc</option> option. You can use <parameter>all</>, -<parameter>to</>, <parameter>cc</>, <parameter>me</> after the -<option>-cc</option> option to have <command>repl</> automatically -add the various addresses to the cc list in the message. You have -probably noticed that the original message isn't included. This is -because most MH setups are configured to do this from the -start.</para> - -</sect1> - -<sect1> -<title><filename>components</>, and <filename>replcomps</>—components files for <command>comp</> and <command>repl</></title> - -<para>The <filename>components</> file is usually in -<filename>/usr/local/lib/mh</filename>. You can copy that file into -your MH Mail directory and edit to contain what you want it to -contain. It is a fairly basic file. You have various email headers at -the top, a dashed line and then nothing. The -<command>comp</command> command just copies this -<filename>components</> file and then edits it. You can add any -kind of valid RFC822 header you want. For instance you could have -something like this in your <filename>components</> file: -<informalexample> -<screen>To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.freebsd.org/ --------</screen> -</informalexample> - -MH would then copy this components file and throw you into your -editor. The <filename>components</> file is fairly simple. If you -wanted to have a signature on those messages you would just put your -signature in that <filename>components</> file.</para> - -<para>The <filename>replcomps</> file is a bit more complex. The default -<filename>replcomps</> looks like this: -<informalexample> -<screen>%(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ -%<(nonnull)%(void(width))%(putaddr To: )\n%>\ -%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ -%<(nonnull)%(void(width))%(putaddr cc: )\n%>\ -%<{fcc}Fcc: %{fcc}\n%>\ -%<{subject}Subject: Re: %{subject}\n%>\ -%<{date}In-reply-to: Your message of "\ -%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} - %{message-id}%>\n%>\ --------- -</screen> -</informalexample></para> - -<para>It's in the same basic format as the <filename>components</> file but -it contains quite a few extra formatting codes. The -<literal>%(lit)</> command makes room for the address. The -<literal>%(formataddr</> is a function that returns a proper email -address. The next part is <literal>%<</literal> which means if and -the <literal>{reply-to}</> means the reply-to field in the original -message. So that might be translated this way: -<informalexample> -<screen>%<<emphasis remap=bf>if</emphasis> {reply-to} <emphasis remap=bf>the original message has a reply-to</emphasis> -then give that to formataddr, %? <emphasis remap=bf>else</emphasis> {from} <emphasis remap=bf>take the -from address</emphasis>, %? <emphasis remap=bf>else</emphasis> {sender} <emphasis remap=bf>take the sender address</emphasis>, %? -<emphasis remap=bf>else</emphasis> {return-path} <emphasis remap=bf>take the return-path from the original -message</emphasis>, %> <emphasis remap=bf>endif</emphasis>.</screen> -</informalexample></para> - -<para>As you can tell MH formatting can get rather involved. You can -probably decipher what most of the other functions and variables -mean. All of the information on writing these format strings is in the -MH-Format man page. The really nice thing is that once you have built -your customized <filename>replcomps</> file you won't need to touch it -again. No other email program really gives you the power and -flexibility that MH gives you.</para> - -</sect1> -</chapter> -</book> diff --git a/en/tutorials/multios/Makefile b/en/tutorials/multios/Makefile deleted file mode 100644 index 8a591510bb..0000000000 --- a/en/tutorials/multios/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.4 1997-07-01 05:38:14 max Exp $ - -DOCS= multios.docb -INDEXLINK= multios.html - -.include "../../web.mk" - diff --git a/en/tutorials/multios/multios.docb b/en/tutorials/multios/multios.docb deleted file mode 100644 index 6ed2e937ef..0000000000 --- a/en/tutorials/multios/multios.docb +++ /dev/null @@ -1,682 +0,0 @@ -<!-- $Id: multios.docb,v 1.4 1998-11-30 23:14:55 billf Exp $ --> -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> - -<bookinfo> -<bookbiblio> -<title>Installing and Using FreeBSD With Other Operating Systems</title> - -<authorgroup> -<author> -<firstname>Jay</firstname> -<surname>Richmond</surname> -<affiliation> -<address> -<email>jayrich@sysc.com</email> -</address> -</affiliation> -</author> -</authorgroup> - -<pubdate>6 August 1996</pubdate> - -<abstract><para>This document discusses how to make FreeBSD coexist -nicely with other popular operating systems such as Linux, MS-DOS, -OS/2, and Windows 95. Special thanks to: Annelise Anderson -<email>andrsn@stanford.edu</email>, Randall Hopper -<email>rhh@ct.picker.com</email>, and Jordan K. Hubbard -<email>jkh@time.cdrom.com</email></para></abstract> - -</bookbiblio> -</bookinfo> - -<chapter> -<title>Overview</title> - -<para>Most people can't fit these operating systems together -comfortably without having a larger hard disk, so special -information on large EIDE drives is included. Because there are so -many combinations of possible operating systems and hard disk -configurations, the <xref linkend="ch5"> section may be of the most use -to you. It contains descriptions of specific working computer setups -that use multiple operating systems.</para> - -<para>This document assumes that you have already made room on your -hard disk for an additional operating system. Any time you -repartition your hard drive, you run the risk of destroying the data -on the original partitions. However, if your hard drive is completely -occupied by DOS, you might find the FIPS utility (included on the -FreeBSD CD-ROM in the <filename>\TOOLS</filename> directory or via -<ulink URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>) -useful. It lets you repartition your hard disk without destroying the -data already on it. There is also a commercial program available -called Partition Magic, which lets you size and delete partitions -without consequence.</para> - -</chapter> - -<chapter id="ch2"> -<title>Overview of Boot Managers</title> - -<para>These are just brief descriptions of some of the different boot -managers you may encounter. Depending on your computer setup, you may -find it useful to use more than one of them on the same -system.</para> - -<variablelist> - -<varlistentry> -<term>Boot Easy</term> - -<listitem> -<para>This is the default boot manager used with FreeBSD. It has the -ability to boot most anything, including BSD, OS/2 (HPFS), Windows 95 -(FAT and FAT32), and Linux. Partitions are selected with the -function keys.</para> -</listitem> -</varlistentry> - -<varlistentry> -<term>OS/2 Boot Manager</term> - -<listitem> -<para>This will boot FAT, HPFS, FFS (FreeBSD), and EXT2 -(Linux). It will also boot FAT32 partitions. Partitions are -selected using arrow keys. The OS/2 Boot Manager is the only one to -use its own separate partition, unlike the others which use the -master boot record (MBR). Therefore, it must be installed below the -1024th cylinder to avoid booting problems. It can boot Linux using -LILO when it is part of the boot sector, not the MBR. Go to <ulink -URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux HOWTOs</ulink> -on the World Wide Web for more information on booting Linux with -OS/2's boot manager.</para> -</listitem> -</varlistentry> - -<varlistentry> -<term>OS-BS</term> - -<listitem> <para>This is an alternative to Boot Easy. It gives you -more control over the booting process, with the ability to set the -default partition to boot and the booting timeout. The beta version -of this programs allows you to boot by selecting the OS with your -arrow keys. It is included on the FreeBSD CD in the -<filename>\TOOLS</filename> directory, and via <ulink -URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>.</para> -</listitem> </varlistentry> - -<varlistentry> -<term>LILO, or LInux LOader</term> - -<listitem> -<para>This is a limited boot manager. Will boot FreeBSD, though some -customization work is required in the LILO configuration file.</para> -</listitem> -</varlistentry> - -</variablelist> - -<note id="fat32"><title>About FAT32</title><para>FAT32 is the replacement to -the FAT filesystem included in Microsoft's OEM SR2 Beta release, -which is expected to utilitized on computers pre-loaded with Windows -95 towards the end of 1996. It converts the normal FAT file system -and allows you to use smaller cluster sizes for larger hard drives. -FAT32 also modifies the traditional FAT boot sector and allocation -table, making it incompatible with some boot managers.</para></note> - -</chapter> - -<chapter id="ch3"> -<title>A Typical Installation</title> - -<para>Let's say I have two large EIDE hard drives, and I want to -install FreeBSD, Linux, and Windows 95 on them.</para> - -<para>Here's how I might do it using these hard disks: -<itemizedlist> - -<listitem> -<para><filename>/dev/wd0</> (first physical hard disk)</para> -</listitem> - -<listitem> -<para><filename>/dev/wd1</> (second hard disk)</para> -</listitem> - -</itemizedlist> -</para> - -<para>Both disks have 1416 cylinders.</para> - -<procedure> - -<step><para>I boot from a MS-DOS or Windows 95 boot disk that -contains the <filename>FDISK.EXE</> utility and make a small 50 meg -primary partition (35-40 for Windows 95, plus a little breathing -room) on the first disk. Also create a larger partition on the -second hard disk for my Windows applications and data.</para></step> - -<step><para>I reboot and install Windows 95 (easier said than done) -on the <filename>C:</> partition.</para> </step> - -<step><para>The next thing I do is install Linux. I'm not sure about -all the distributions of Linux, but slackware includes LILO (see -<xref linkend="ch2">). When I am partitioning out my hard disk with -Linux <command>fdisk</command>, I would put all of Linux on the first -drive (maybe 300 megs for a nice root partition and some swap -space).</para></step> - -<step><para>After I install Linux, and are prompted about installing -LILO, make SURE that I install it on the boot sector of my root -Linux partition, not in the MBR (master boot record).</para></step> - -<step><para>The remaining hard disk space can go to FreeBSD. I also -make sure that my FreeBSD root slice does not go beyond the 1024th -cylinder. (The 1024th cylinder is 528 megs into the disk with our -hypothetical 720MB disks). I will use the rest of the hard drive -(about 270 megs) for the <filename>/usr</> and <filename>/</> slices -if I wish. The rest of the second hard disk (size depends on the -amount of my Windows application/data partition that I created in -step 1 can go to the <filename>/usr/src</> slice and swap -space.</para></step> - -<step><para>When viewed with the Windows 95 <command>fdisk</> utility, my hard drives -should now look something like this: -<screen> ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- -</screen> -** May say FAT16 or FAT32 if you are using the OEM SR2 update. -See <xref linkend="ch2">).</para></step> - -<step><para>Install FreeBSD. I make sure to boot with my first hard -disk set at <quote>NORMAL</> in the BIOS. If it is not, I'll have -the enter my true disk geometry at boot time (to get this, boot -Windows 95 and consult Microsoft Diagnostics (<filename>MSD.EXE</>), -or check your BIOS) with the parameter <literal>hd0=1416,16,63</> -where <replaceable>1416</> is the number of cylinders on my hard -disk, <replaceable>16</> is the number of heads per track, and -<replaceable>63</> is the number of sectors per track on the -drive.</para></step> - -<step><para>When partitioning out the hard disk, I make sure to install -Boot Easy on the first disk. I don't worry about the second disk, -nothing is booting off of it.</para></step> - -<step><para>When I reboot, Boot Easy should recognize my three -bootable partitions as DOS (Windows 95), Linux, and BSD -(FreeBSD).</para></step> - -</procedure> - -</chapter> - -<chapter id="ch4"> -<title>Special Considerations</title> - -<para>Most operating systems are very picky about where and how they are -placed on the hard disk. Windows 95 and DOS need to be on the first -primary partitiin on the first hard disk. OS/2 is the exception. It -can be installed on the first or second disk in a primary or extended -partition. If you are not sure, keep the beginning of the bootable -partitions below the 1024th cylinder.</para> - -<para>If you install Windows 95 on an existing BSD system, it will -<quote>destroy</> the MBR, and you will have to reinstall your -previous boot manager. Boot Easy can be reinstalled by using the -BOOTINST.EXE utility included in the \TOOLS directory on the CD-ROM, -and via <ulink -URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>. You can -also re-start the installation process and go to the partition -editor. From there, mark the FreeBSD partition as bootable, -select Boot Manager, and then type W to (W)rite out the information -to the MBR. You can now reboot, and Boot Easy should then -recognize Windows 95 as DOS.</para> - -<para>Please keep in mind that OS/2 can read FAT and HPFS partitions, -but not FFS (FreeBSD) or EXT2 (Linux) partitions. Likewise, Windows -95 can only read and write to FAT and FAT32 (see <xref -linkend="ch2">) partitions. FreeBSD can read most file systems, but -currently cannot read HPFS partitions. Linux can read HPFS -partitions, but can't write to them. Recent versions of the Linux -kernel (2.x) can read and write to Windows 95 VFAT partitions (VFAT -is what gives Windows 95 long file names - it's pretty much the same -as FAT). Linux can read and write to most file systems. Got that? -I hope so.</para> - -</chapter> - -<chapter id="ch5"> -<title>Examples</title> - -<para><emphasis>(section needs work, please send your example to -<email>jayrich@sysc.com</email>)</emphasis>.</para> - -<para>FreeBSD+Win95: If you installed FreeBSD after Windows 95, you -should see <literal>DOS</> on the Boot Easy menu. This is Windows -95. If you installed Windows 95 after FreeBSD, read <xref -linkend="ch4"> above. As long as your hard disk does not have 1024 -cylinders you should not have a problem booting. If one of your -partitions goes beyond the 1024th cylinder however, and you get -messages like <errorname>invalid system disk</> under DOS (Windows 95) -and FreeBSD will not boot, try looking for a setting in your BIOS -called <quote>> 1024 cylinder support</> or <quote>NORMAL/LBA</> -mode. DOS may need LBA (Logical Block Addressing) in order to boot -correctly. If the idea of switching BIOS settings every time you -boot up doesn't appeal to you, you can boot FreeBSD through DOS via -the <filename>FBSDBOOT.EXE</> utility on the CD (It should find your -FreeBSD partition and boot it.)</para> - -<para>FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger -can boot all of these operating systems, so that shouldn't be a -problem.</para> - -<para>FreeBSD+Linux: You can also use Boot Easy to boot both operating -systems.</para> - -<para>FreeBSD+Linux+Win95: (see <xref linkend="ch3">)</para> - -</chapter> - -<chapter id="sources"> -<title>Other Sources of Help</title> - -<para>There are many <ulink -URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux HOW-TOs</ulink> that -deal with multiple operating systems on the same hard disk.</para> - -<para>The <ulink -URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2 -mini-HOWTO</ulink> offers help on configuring the OS/2 boot manager, and the -<ulink -URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD -mini-HOWTO</ulink> might be interesting as well. The <ulink -URL="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO</ulink> is -also helpful.</para> - -<para>The <ulink -URL="http://www.dorsai.org/~dcl/publications/NTLDR_Hacking">NT Loader -Hacking Guide</ulink> provides good information on multibooting -Windows NT, '95, and DOS with other operating systems.</para> - -<para>And Hale Landis's "How It Works" document pack contains some good info -on all sorts of disk geometry and booting related topics. Here are a few -links that might help you find it: <ulink URL="ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip">ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip</ulink>, -<ulink URL="http://web.idirect.com/~frank/">http://www.cs.yorku.ca/People/frank/docs/</ulink>.</para> - -<para>Finally, don't overlook FreeBSD's kernel documentation on the booting -procedure, available in the kernel source distribution (it unpacks to -<ulink URL="file:/usr/src/sys/i386/boot/biosboot/README.386BSD">file:/usr/src/sys/i386/boot/biosboot/README.386BSD</ulink>.</para> - -</chapter> - -<chapter> -<title>Technical Details</title> - -<para><emphasis>(Contributed by Randall Hopper, -<email>rhh@ct.picker.com</email>)</emphasis></para> - -<para>This section attempts to give you enough basic information -about your hard disks and the disk booting process so that you can -troubleshoot most problems you might encounter when getting set up to -boot several operating systems. It starts in pretty basic terms, so -you may want to skim down in this section until it begins to look -unfamiliar and then start reading.</para> - - -<sect1> -<title>Disk Primer</title> - -<para>Three fundamental terms are used to describe the location of -data on your hard disk: Cylinders, Heads, and Sectors. It's not -particularly important to know what these terms relate to except to -know that, together, they identify where data is physically on your -disk.</para> - -<para>Your disk has a particular number of cylinders, number of -heads, and number of sectors per cylinder-head (a cylinder-head also -known nown as a track). Collectively this information defines the -"physical disk geometry" for your hard disk. There are typically 512 -bytes per sector, and 63 sectors per track, with the number of -cylinders and heads varying widely from disk to disk. Thus you can -figure the number of bytes of data that'll fit on your own disk by -calculating: <informalexample><para>(# of cylinders) × (# -heads) × (63 sectors/track) × (512 -bytes/sect)</></informalexample> For example, on my 1.6 Gig Western -Digital AC31600 EIDE hard disk,that's: <informalexample><para>(3148 -cyl) × (16 heads) × (63 sectors/track) × (512 -bytes/sect)</para></informalexample></para> - -<para>which is 1,624,670,208 bytes, or around 1.6 Gig.</para> - -<para>You can find out the physical disk geometry (number of -cylinders, heads, and sectors/track counts) for your hard disks using -ATAID or other programs off the net. Your hard disk probably came -with this information as well. Be careful though: if you're using -BIOS LBA (see <xref linkend="limits">), you can't use just any -program to get the physical geometry. This is because many programs -(e.g. <filename>MSD.EXE</> or FreeBSD fdisk) don't identify the -physical disk geometry; they instead report the -<firstterm>translated geometry</> (virtual numbers from using LBA). -Stay tuned for what that means.</para> - -<para>One other useful thing about these terms. Given 3 -numbers—a cylinder number, a head number, and a -sector-within-track number—you identify a specific absolute -sector (a 512 byte block of data) on your disk. Cylinders and Heads -are numbered up from 0, and Sectors are numbered up from 1.</para> - -<para>For those that are interested in more technical details, -information on disk geometry, boot sectors, BIOSes, etc. can be found -all over the net. Query Lycos, Yahoo, etc. for <literal>boot -sector</> or <literal>master boot record</>. Among the useful info -you'll find are Hale Landis's <citetitle>How It Works</> document -pack. See the <xref linkend="sources"> section for a few pointers to -this pack.</para> - -<para>Ok, enough terminology. We're talking about booting -here.</para> - -</sect1> - -<sect1 id="booting"> -<title>The Booting Process</title> - -<para>On the first sector of your disk (Cyl 0, Head 0, Sector 1) -lives the Master Boot Record (MBR). It contains a map of your disk. -It identifies up to 4 <firstterm>partitions</>, each of which is a -contiguous chunk of that disk. FreeBSD calls partitions -<firstterm>slices</> to avoid confusion with it's own partitions, but -we won't do that here. Each partition can contain its own operating -system.</para> - -<para>Each partition entry in the MBR has a <firstterm>Partition -ID</>, a <firstterm>Start Cylinder/Head/Sector</>, and an -<firstterm>End Cylinder/Head/Sector</>. The Partition ID tells what -type of partition it is (what OS) and the Start/End tells where it -is. <xref linkend="tbl-pid"> lists a smattering of some common -Partition IDs.</para> - -<table id="tbl-pid"> -<title>Partition IDs</> -<tgroup cols="2"> -<thead> -<row> -<entry>ID (hex)</entry> -<entry>Description</entry> -</row> -</thead> - -<tbody> -<row> -<entry>01</entry> -<entry>Primary DOS12 (12-bit FAT)</entry> -</row> - -<row> -<entry>04</entry> -<entry>Primary DOS16 (16-bit FAT)</entry> -</row> - -<row> -<entry>05</entry> -<entry>Extended DOS</entry> -</row> - -<row> -<entry>06</entry> -<entry>Primary big DOS (> 32MB)</entry> -</row> - -<row> -<entry>0A</entry> -<entry>OS/2</entry> -</row> - -<row> -<entry>83</entry> -<entry>Linux (EXT2FS)</entry> -</row> - -<row> -<entry>A5</entry> -<entry>FreeBSD, NetBSD, 386BSD (UFS)</entry> -</row> - -</tbody> -</tgroup> -</table> - -<para>Note that not all partitions are bootable (e.g. Extended DOS). -Some are—some aren't. What makes a partition bootable is the -configuration of the <firstterm>Partition Boot Sector</> that exists -at the beginning of each partition.</para> - -<para>When you configure your favorite boot manager, it looks up the entries -in the MBR partition tables of all your hard disks and lets you name the -entries in that list. Then when you boot, the boot manager is invoked by -special code in the Master Boot Sector of the first probed hard disk on -your system. It looks at the MBR partition table entry corresponding to -the partition choice you made, uses the Start Cylinder/Head/Sector -information for that partition, loads up the Partition Boot Sector for that -partition, and gives it control. That Boot Sector for the partition itself -contains enough information to start loading the operating system on that -partition.</para> - -<para>One thing we just brushed past that's important to know. All of your -hard disks have MBRs. However, the one that's important is the one on the -disk that's first probed by the BIOS. If you have only IDE hard disks, its -the first IDE disk (e.g. primary disk on first controller). Similarly for -SCSI only systems. If you have both IDE and SCSI hard disks though, the -IDE disk is typically probed first by the BIOS, so the first IDE disk is -the first probed disk. The boot manager you will install will be hooked into -the MBR on this first probed hard disk that we've just described.</para> - -</sect1> - -<sect1 id="limits"> -<title>Booting Limitations and Warnings</title> - -<para>Now the interesting stuff that you need to watch out for.</para> - -<sect2> -<title>The dreaded 1024 cylinder limit and how BIOS LBA helps</title> - -<para>The first part of the booting process is all done through the -BIOS, (if that's a new term to you, the BIOS is a software chip on -your system motherboard which provides startup code for your -computer). As such, this first part of the process is subject to the -limitations of the BIOS interface.</para> - -<para>The BIOS interface used to read the hard disk during this period -(INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 -bits to the Head Number, and 6 bits to the Sector Number. This -restricts users of this interface (i.e. boot managers hooked into -your disk's MBR as well as OS loaders hooked into the Boot Sectors) -to the following limits: -<itemizedlist> -<listitem><para>1024 cylinders, max</para></listitem> -<listitem><para>256 heads , max</para></listitem> -<listitem><para>64 sectors/track, max (actually 63, <literal>0</> isn't -available)</para></listitem> -</itemizedlist> -</para> - -<para>Now big hard disks have lots of cylinders but not a lot of -heads, so invariably with big hard disks the number of cylinders is -greater than 1024. Given this and the BIOS interface as is, you -can't boot off just anywhere on your hard disk. The boot code (the -boot manager and the OS loader hooked into all bootable partitions' -Boot Sectors) has to reside below cylinder 1024. In fact, if your -hard disk is typical and has 16 heads, this equates to: -<informalexample> -<para>1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) -× 512 bytes/sector</para> -</informalexample> -</para> - -<para>which is around the often-mentioned 528MB limit.</para> - -<para>This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA -gives the user of the BIOS API calls access to physical cylinders above -1024 though the BIOS interfaces by redefining a cylinder. That is, it -remaps your cylinders and heads, making it appear through the BIOS as -though the disk has fewer cylinders and more heads than it actually -does. In other words, it takes advantage of the fact that hard disks have -relatively few heads and lots of cylinders by shifting the balance between -number of cylinders and number of heads so that both numbers lie below the -above-mentioned limits (1024 cylinders, 256 heads).</para> - -<para>With BIOS LBA, the hard disk size limitation is virtually -removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA -BIOS, you can put FreeBSD or any OS anywhere you want and not hit the -1024 cylinder limit.</para> - -<para>To use my 1.6 Gig Western Digital as an example again, it's -physical geometry is: -<informalexample> -<para>(3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector)</para> -</informalexample> -</para> - -<para>However, my BIOS LBA remaps this to: -<informalexample> -<para>( 787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector)</para> -</informalexample> -</para> - -<para>giving the same effective size disk, but with cylinder and head -counts within the BIOS API's range (Incidentally, I have both Linux and -FreeBSD existing on one of my hard disks above the 1024th physical -cylinder, and both operating systems boot fine, thanks to BIOS LBA).</para> - -</sect2> - -<sect2> -<title>Boot Managers and Disk Allocation</title> - -<para>Another gotcha to watch out when installing boot managers is -allocating space for your boot manager. It's best to be aware of -this issue up front to save yourself from having to reinstall one or -more of your OSs.</para> - -<para>If you followed the discussion in <xref linkend="booting"> -about the Master Boot Sector (where the MBR is), Partition Boot -Sectors, and the booting process, you may have been wondering just -exactly where on your hard disk that nifty boot manager is going to -live. Well, some boot managers are small enough to fit entirely -within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along -with the partition table. Others need a bit more room and actually -extend a few sectors past the Master Boot Sector in the Cylinder 0 -Head 0 track, since that's typically free…typically.</para> - -<para>That's the catch. Some operating systems (FreeBSD included) let -you start their partitions right after the Master Boot Sector at -Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give -FreeBSD's sysinstall a disk with an empty chunk up front or the whole -disk empty, that's where it'll start the FreeBSD partition by default -(at least it did when I fell into this trap). Then when you go to -install your boot manager, if it's one that occupies a few extra -sectors after the MBR, it'll overwrite the front of the first -partition's data. In the case of FreeBSD, this overwrites the -disk label, and renders your FreeBSD partition unbootable.</para> - -<para>The easy way to avoid this problem (and leave yourself the -flexibility to try different boot managers later) is just to always -leave the first full track on your disk unallocated when you -partition your disk. That is, leave the space from Cylinder 0, Head -0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and -start your first partition at Cylinder 0, Head 1, Sector 1. -For what it's worth, when you create a DOS partition at the -front of your disk, DOS leaves this space open by default (this is -why some boot managers assume it's free). So creating a DOS -partition up at the front of your disk avoids this problem -altogether. I like to do this myself, creating 1 Meg DOS partition -up front, because it also avoids my primary DOS drive letters -shifting later when I repartition.</para> - -<para>For reference, the following boot managers use the -Master Boot Sector to store their code and data: -<itemizedlist> - -<listitem> -<para>OS-BS 1.35</para> -</listitem> - -<listitem> -<para>Boot Easy</para> -</listitem> - -<listitem> -<para>LILO</para> -</listitem> - -</itemizedlist> -</para> - -<para>These boot managers use a few additional sectors after the -Master Boot Sector: -<itemizedlist> - -<listitem> -<para>OS-BS 2.0 Beta 8 (sectors 2-5)</para> -</listitem> - -<listitem> -<para>OS/2's boot manager</para> -</listitem> - -</itemizedlist> -</para> - -</sect2> - -<sect2> -<title>What if your machine won't boot?</title> - -<para>At some point when installing boot managers, you might leave the -MBR in a state such that your machine won't boot. This is unlikely, -but possible when re-FDISKing underneath an already-installed boot -manager.</para> - -<para>If you have a bootable DOS partition on your disk, you can boot -off a DOS floppy, and run: -<informalexample> -<screen>A:\> <userinput>FDISK /MBR</></screen> -</informalexample> -</para> - -<para>to put the original, simple DOS boot code back into the system. You can -then boot DOS (and DOS only) off the hard drive. Alternatively, just -re-run your boot manager installation program off a bootable floppy.</para> - -</sect2> -</sect1> -</chapter> -</book> diff --git a/en/tutorials/newuser/Makefile b/en/tutorials/newuser/Makefile deleted file mode 100644 index d8131087f4..0000000000 --- a/en/tutorials/newuser/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:15 max Exp $ - -DOCS= newuser.docb -INDEXLINK= newuser.html - -.include "../../web.mk" - diff --git a/en/tutorials/newuser/newuser.docb b/en/tutorials/newuser/newuser.docb deleted file mode 100644 index c8ab990405..0000000000 --- a/en/tutorials/newuser/newuser.docb +++ /dev/null @@ -1,943 +0,0 @@ -<!-- $Id: newuser.docb,v 1.5 1998-08-09 22:53:56 wosch Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> -<book> - -<bookinfo> -<bookbiblio> -<title>For People New to Both FreeBSD and Unix</title> - -<authorgroup> -<author> -<firstname>Annelise</firstname> -<surname>Anderson</surname> -<affiliation> -<address><email>andrsn@andrsn.stanford.edu</email></address> -</affiliation> -</author> -</authorgroup> - -<pubdate>August 15, 1997</pubdate> - -<abstract><para>Congratulations on installing FreeBSD! This -introduction is for people new to both FreeBSD -<emphasis>and</emphasis> Un*x—so it starts with basics. It -assumes you're using version 2.0.5 or later of FreeBSD as distributed -by Walnut Creek or FreeBSD.ORG, your system (for now) has a single -user (you)—and you're probably pretty good with DOS/Windows or -OS/2.</para></abstract> - -</bookbiblio> -</bookinfo> - -<chapter> -<title>Logging in and Getting Out</title> - -<para>Log in (when you see <systemitem -class=prompt>login:</systemitem>) as a user you created during -installation or as <firstterm>root</firstterm>. (Your FreeBSD -installation will already have an account for root; root can go -anywhere and do anything, including deleting essential files, so be -careful!) The symbols % and # in the following stand for the prompt -(yours may be different), with % indicating an ordinary user and -# indicating root. </para> - -<para>To log out (and get a new <systemitem class=prompt>login:</systemitem> prompt) type -<informalexample> -<screen># <userinput>exit</userinput></screen> -</informalexample> -as often as necessary. Yes, press <keysym>enter</keysym> after -commands, and remember that Unix is -case-sensitive—<command>exit</command>, not -<command>EXIT</command>.</para> - -<para>To shut down the machine type: -<informalexample> -<screen># <userinput>/sbin/shutdown -h now</userinput></screen> -</informalexample> -Or to reboot type -<informalexample> -<screen># <userinput>/sbin/shutdown -r now</userinput></screen> -</informalexample> -or -<informalexample> -<screen># <userinput>/sbin/reboot</userinput></screen> -</informalexample> -</para> - -<para>You can also reboot with -<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>. -Give it a little time to do its work. This is equivalent to -<command>/sbin/reboot</command> in recent releases of FreeBSD, and is -much, much better than hitting the reset button. You don't want to -have to reinstall this thing, do you?</para> - -</chapter> - -<chapter> -<title>Adding A User with Root Privileges</title> - -<para>If you didn't create any users when you installed the system and -are thus logged in as root, you should probably create a user now with -<informalexample> -<screen># <userinput>adduser</userinput></screen> -</informalexample> -The first time you use adduser, it might ask for some defaults to save. You -might want to make the default shell csh instead of sh, if it suggests -sh as the default. Otherwise just press enter to accept each default. -These defaults are saved in <filename>/etc/adduser.conf</filename>, -an editable file.</para> - -<para>Suppose you create a user <emphasis>jack</emphasis> with -full name <emphasis>Jack Benimble</emphasis>. Give jack a password -if security (even kids around who might pound on the keyboard) is an -issue. When it asks you if you want to invite jack into other -groups, type <userinput>wheel</userinput> -<informalexample> -<screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput></screen> -</informalexample> -This will make it possible to log in as <emphasis>jack</emphasis> and -use the <command>su</command> command to become root. Then you won't -get scolded any more for logging in as root.</para> - -<para>You can quit <command>adduser</command> any time by typing -<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>, and at -the end you'll have a chance to approve your new user or simply type -<keycap>n</keycap> for no. You might want to create a -second new user (jill?) so that when you edit jack's login files, -you'll have a hot spare in case something goes wrong.</para> - -<para>Once you've done this, use <command>exit</command> -to get back to a login prompt and log in as -<emphasis>jack</emphasis>. In general, it's a good idea to do as -much work as possible as an ordinary user who doesn't have the -power—and risk—of root.</para> - -<para>If you already created a user and you want the user to be able -to <command>su</command> to root, you can log in as root -and edit the file <filename>/etc/group</filename>, adding jack to the -first line (the group wheel). But first you need to practice -<command>vi</command>, the text editor--or use the simpler text -editor, <command>ee</command>, installed on recent version of -FreeBSD.</para> - -<para>To delete a user, use the <command>rmuser</command> command.</para> - -</chapter> - -<chapter> -<title>Looking Around</title> - -<para>Logged in as an ordinary user, look around and try out some -commands that will access the sources of help and information within -FreeBSD.</para> - -<para>Here are some commands and what they do: -<variablelist> -<varlistentry><term><command>id</command></term> -<listitem> -<para>Tells you who you are!</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>pwd</command></term> - -<listitem> -<para>Shows you where you are—the current -working directory.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls</command></term> - -<listitem> -<para>Lists the files in the current directory.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls <option>-F</option></command></term> - -<listitem> -<para>Lists the files in the current directory with a -<literal>*</literal> after executables, a <literal>/</literal> after -directories, and an <literal>@</literal> after symbolic links.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls <option>-l</option></command></term> - -<listitem> -<para>Lists the files in long format—size, -date, permissions.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls <option>-a</option></command></term> - -<listitem> -<para>Lists hidden <quote>dot</quote> -files with the others. If you're root, the<quote>dot</quote> files -show up without the <option>-a</option> switch.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>cd</command></term> - -<listitem> -<para>Changes directories. <command>cd -<parameter>..</parameter></command> backs up one level; note the -space after <command>cd</command>. <command>cd -<parameter>/usr/local</parameter></command> goes there. <command>cd -<parameter>~</parameter></command> goes to the home directory of the -person logged in—e.g., <filename>/usr/home/jack</filename>. -Try <command>cd <parameter>/cdrom</parameter></command>, and then -<command>ls</command>, to find out if your CDROM is mounted and -working.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>view <replaceable>filename</replaceable></command></term> - -<listitem> -<para>Lets you look at a file (named -<replaceable>filename</replaceable> without changing it. Try -<command>view <parameter>/etc/fstab</parameter></command>. -<command>:q</command> to quit.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>cat <replaceable>filename</replaceable></command></term> - -<listitem> - -<para>Displays <replaceable>filename</replaceable> on screen. If -it's too long and you can see only the end of it, press -<keycap>ScrollLock</keycap> and use the <keycap>up-arrow</keycap> to -move backward; you can use <keycap>ScrollLock</keycap> with man pages -too. Press <keycap>ScrollLock</keycap> again to quit scrolling. You -might want to try <command>cat</command> on some of the dot files in -your home directory—<command>cat -<parameter>.cshrc</parameter></command>, <command>cat -<parameter>.login</parameter></command>, <command>cat -<parameter>.profile</parameter></command>.</para> - -</listitem> -</varlistentry> -</variablelist> - -You'll notice aliases in <filename>.cshrc</filename> for some of the -<command>ls</command> commands (they're very convenient). -You can create other aliases by editing <filename>.cshrc</filename>. -You can make these aliases available to all users on the system by -putting them in the system-wide csh configuration file, -<filename>/etc/csh.cshrc</filename>.</para> - -</chapter> - -<chapter> -<title>Getting Help and Information</title> - -<para>Here are some useful sources of help. -<replaceable>Text</replaceable> stands for something of your choice -that you type in—usually a command or filename.</para> - -<variablelist> -<varlistentry><term><command>apropos <replaceable>text</replaceable></command></term> - -<listitem> -<para>Everything containing string <replaceable>text</replaceable> -in the <database>whatis database</database>.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>man <replaceable>text</replaceable></command></term> - -<listitem> -<para>The man page for <replaceable>text</replaceable>. The major -source of documentation for Un*x systems. <command>man -<parameter>ls</parameter></command> will tell you all the ways to use -the <command>ls</command> command. Press <keycap>Enter</keycap> to -move through text, -<keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> to go -back a page, <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo> to -go forward, <keycap>q</keycap> or -<keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo> to -quit.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>which <replaceable>text</replaceable></command></term> - -<listitem> -<para>Tells you where in the user's path the command -<replaceable>text</replaceable> is found.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>locate <replaceable>text</replaceable></command></term> - -<listitem> -<para>All the paths where the string <replaceable>text</replaceable> -is found.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>whatis <replaceable>text</replaceable></command></term> - -<listitem> -<para>Tells you what the command <replaceable>text</replaceable> -does and its man page. Typing <command>whatis *</command> will tell -you about all the binaries in the current directory.</para> -</listitem> -</varlistentry> - -<varlistentry><term><command>whereis <replaceable>text</replaceable></command></term> - -<listitem> -<para>Finds the file <replaceable>text</replaceable>, giving its full -path.</para> -</listitem> -</varlistentry> -</variablelist> - -<para>You might want to try using <command>whatis</command> on some -common useful commands like <command>cat</command>, -<command>more</command>, <command>grep</command>, -<command>mv</command>, <command>find</command>, -<command>tar</command>, <command>chmod</command>, -<command>chown</command>, <command>date</command>, and -<command>script</command>. <command>more</command> lets you read a -page at a time as it does in DOS, e.g., <command>ls -l | -more</command> or <command>more -<replaceable>filename</replaceable></command>. The -<literal>*</literal> works as a wildcard—e.g., <command>ls -w*</command> will show you files beginning with -<literal>w</literal>.</para> - -<para>Are some of these not working very well? Both -<command>locate</command> and <command>whatis</command> -depend on a database that's rebuilt weekly. If your machine isn't -going to be left on over the weekend (and running FreeBSD), you might -want to run the commands for daily, weekly, and monthly maintenance -now and then. Run them as root and give each one time to finish -before you start the next one, for now. -<informalexample> -<screen># <userinput>/etc/daily</userinput> -<lineannotation>output omitted</lineannotation> -# <userinput>/etc/weekly</userinput> -<lineannotation>output omitted</lineannotation> -# <userinput>/etc/monthly</userinput> -<lineannotation>output omitted</lineannotation></screen> -</informalexample></para> - -<para>If you get tired waiting, press -<keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to get -another <firstterm>virtual console</firstterm>, and log in again. -After all, it's a multi-user, multi-tasking system. Nevertheless -these commands will probably flash messages on your screen while -they're running; you can type <command>clear</command> at the prompt -to clear the screen. Once they've run, you might want to look at -<filename>/var/mail/root</filename> and -<filename>/var/log/messages</filename>.</para> - -<para>Basically running such commands is part of system -administration—and as a single user of a Unix system, you're -your own system administrator. Virtually everything you need to be -root to do is system administration. Such responsibilities aren't -covered very well even in those big fat books on Unix, which seem to -devote a lot of space to pulling down menus in windows managers. You -might want to get one of the two leading books on systems -administration, either Evi Nemeth et.al.'s <citetitle>UNIX System -Administration Handbook</citetitle> (Prentice-Hall, 1995, ISBN -0-13-15051-7)—the second edition with the red cover; or -Æleen Frisch's <citetitle>Essential System -Administration</citetitle> (O'Reilly & Associates, 1993, ISBN -0-937175-80-3). I used Nemeth.</para> - -</chapter> - -<chapter> -<title>Editing Text</title> - -<para>To configure your system, you need to edit text files. Most of -them will be in the <filename>/etc</filename> directory; and you'll -need to <command>su</command> to root to be able to change them. You -can use the easy <command>ee</command>, but in the long run the -text editor <command>vi</command> is worth learning. There's an -excellent tutorial on vi in -<filename>/usr/src/contrib/nvi/docs/tutorial</filename> if you have -that installed; otherwise you can get it by ftp to -ftp.cdrom.com in the directory -FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial.</para> - -<para>Before you edit a -file, you should probably back it up. Suppose you want to edit -<filename>/etc/rc.conf</filename>. You could just use <command>cd -/etc</command> to get to the <filename>/etc</filename> directory and -do: -<informalexample> -<screen># <userinput>cp rc.conf rc.conf.orig</userinput></screen> -</informalexample> - -This would copy <filename>rc.conf</filename> to -<filename>rc.conf.orig</filename>, and you could later copy -<filename>rc.conf.orig</filename> to <emphasis -remap=tt>rc.conf</emphasis> to recover the original. But even -better would be moving (renaming) and then copying back: -<informalexample> -<screen># <userinput>mv rc.conf rc.conf.orig</userinput> -# <userinput>cp rc.conf.orig rc.conf</userinput></screen> -</informalexample> - -because the <command>mv</command> command preserves the original date -and owner of the file. You can now edit -<filename>rc.conf</filename>. If you want the original back, you'd -then <userinput>mv rc.conf rc.conf.myedit</userinput> -(assuming you want to preserve your edited version) and then -<informalexample> -<screen># <userinput>mv rc.conf.orig rc.conf</userinput></screen> -</informalexample> -to put things back the way they were.</para> - -<para>To edit a file, type -<informalexample> -<screen># <userinput>vi <replaceable>filename</replaceable></userinput></screen> -</informalexample> -Move through the text with the arrow keys. <keycap>Esc</keycap> (the -escape key) puts <command>vi</command> in command mode. Here are some -commands: -<variablelist> -<varlistentry><term><command>x</command></term> -<listitem> -<para>delete letter the cursor is on</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>dd</command></term> - -<listitem> -<para>delete the entire line (even if it wraps on the screen)</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>i</command></term> - -<listitem> -<para>insert text at the cursor</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>a</command></term> - -<listitem> -<para>insert text after the cursor</para> - -</listitem> -</varlistentry> -</variablelist> -Once you type <command>i</command> or <command>a</command>, you can enter text. -<command>Esc</command> puts you back in command mode where you can type -<variablelist> -<varlistentry><term><command>:w</command></term> -<listitem> -<para>to write your changes to disk and continue editing</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>:wq</command></term> - -<listitem> -<para>to write and quit</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>:q!</command></term> - -<listitem> -<para>to quit without saving changes</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>/<replaceable>text</replaceable></command></term> - -<listitem> -<para>to move the cursor to <replaceable>text</replaceable>; -<command>/<keycap>Enter</keycap></command> (the enter key) to find -the next instance of <replaceable>text</replaceable>.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>G</command></term> - -<listitem> -<para>to go to the end of the file</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command><replaceable>n</replaceable>G</command></term> - -<listitem> -<para>to go to line <replaceable>n</replaceable> in -the file, where <replaceable>n</replaceable> is a number</para> - -</listitem> -</varlistentry> - -<varlistentry><term><keycombo><keycap>Ctrl</><keycap>L</></keycombo></term> - -<listitem> -<para>to redraw the screen</para> - -</listitem> -</varlistentry> - -<varlistentry><term><keycombo><keycap>Ctrl</><keycap>b</></> and <keycombo><keycap>Ctrl</><keycap>f</></></term> - -<listitem> -<para>go back -and forward a screen, as they -do with <command>more</> and <command>view</>.</para> - -</listitem> -</varlistentry> -</variablelist> -</para> - -<para>Practice with <command>vi</> in your home directory by creating -a new file with <command>vi <replaceable>filename</></> and adding -and deleting text, saving the file, and calling it up again. -<command>vi</> delivers some surprises because it's really quite -complex, and sometimes you'll inadvertently issue a command that will -do something you don't expect. (Some people actually like -<command>vi</>—it's more powerful than DOS EDIT—find out -about the <command>:r</> command.) Use <keycap>Esc</> one or -more times to be sure you're in command mode and proceed from there -when it gives you trouble, save often with <command>:w</>, and -use <command>:q!</> to get out and start over (from -your last <command>:w</>) when you need to.</para> - -<para>Now you can <command>cd</> to <filename>/etc</filename>, -<command>su</> to root, use <command>vi</> to edit the file -<filename>/etc/group</filename>, and add a user to wheel so the user -has root privileges. Just add a comma and the user's login name to -the end of the first line in the file, press <keycap>Esc</>, and use -<command>:wq</> to write the file to disk and quit. Instantly -effective. (You didn't put a space after the comma, did you?)</para> - -</chapter> - -<chapter> -<title>Printing Files from DOS</title> - -<para>At this point you probably don't have the printer working, so here's a -way to create a file from a man page, move it to a floppy, and then -print it from DOS. Suppose you want to read carefully about changing -permissions on files (pretty important). You can use the command -man chmod to read about it. The command -<informalexample> -<screen># <userinput>man chmod | col -b > chmod.txt</></screen> -</informalexample> -will remove formatting codes and send the man page to -the <filename>chmod.txt</filename> file -instead of showing it on your screen. Now put a dos-formatted -diskette in your floppy drive a, <command>su</> to -root, and type -<informalexample> -<screen># <userinput>/sbin/mount -t msdos /dev/fd0 /mnt</></screen> -</informalexample> -to mount the floppy drive on <filename>/mnt</filename>.</para> - -<para>Now (you no longer need to be root, and you can type -<command>exit</> to get back to being user jack) you can go to the -directory where you created chmod.txt and copy the file to the floppy -with: -<informalexample> -<screen>% <userinput>cp chmod.txt /mnt</></screen> -</informalexample> -and use <command>ls /mnt</command> to get a directory listing of -<filename>/mnt</filename>, which should show the file -<filename>chmod.txt</filename>.</para> - -<para>You might especially want to make a file from -<filename>/sbin/dmesg</filename> by typing -<informalexample> -<screen>% <userinput>/sbin/dmesg > dmesg.txt</></screen> -</informalexample> -and copying <filename>dmesg.txt</filename> to the floppy. -<command>/sbin/dmesg</command> is the boot log record, and it's -useful to understand it because it shows what FreeBSD found when it -booted up. If you ask questions on -<email>freebsd-questions@FreeBSD.ORG</> or on a USENET -group—like <quote>FreeBSD isn't finding my tape drive, what do -I do?</quote>—people will want to know what <command>dmesg</> -has to say.</para> - -<para>You can now dismount the floppy drive (as root) to get the disk -out with -<informalexample> -<screen># <userinput>/sbin/umount /mnt</></screen> -</informalexample> -and reboot to go to DOS. Copy these files to a DOS directory, call -them up with DOS EDIT, Windows Notepad or Wordpad, or a word processor, make a -minor change so the file has to be saved, and print as you normally -would from DOS or Windows. Hope it works! man pages come out best if -printed with the dos <command>print</> command. (Copying files from -FreeBSD to a mounted dos partition is in some cases still a little -risky.)</para> - -<para>Getting the printer printing from FreeBSD involves creating an -appropriate entry in <filename>/etc/printcap</filename> and creating -a matching spool directory in -<filename>/var/spool/output</filename>. If your printer is on -<hardware>lpt0</> (what dos calls <hardware>LPT1</>), you may only -need to go to <filename>/var/spool/output</filename> and (as root) -create the directory <filename>lpd</> by typing: -<command> -mkdir lpd</command>, if it doesn't already -exist. -Then the printer should respond if it's turned on when the system is -booted, and lp or lpr should send a file to the printer. Whether or -not the file actually prints depends on configuring it, which is -covered in the <ulink -URL="../../handbook/handbook.html">FreeBSD -handbook.</></para> - -</chapter> - -<chapter> -<title>Other Useful Commands</title> - -<para> -<variablelist> -<varlistentry><term><command>df</></term> -<listitem> -<para>shows file space and mounted systems.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ps aux</></term> - -<listitem> -<para>shows processes running. <command>ps ax</> is a narrower form.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>rm <replaceable>filename</></></term> - -<listitem> -<para>remove <replaceable>filename</>.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>rm -R <replaceable>dir</></></term> - -<listitem> -<para>removes a directory <replaceable>dir</> and all -subdirectories—careful!</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>ls -R</command></term> - -<listitem> -<para>lists files in the current -directory and all subdirectories; -I used a variant, <command>ls -AFR > where.txt</command>, -to get a list of all -the files in <filename>/</filename> and (separately) -<filename>/usr</filename> before I found better -ways to find files.</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>passwd</></term> - -<listitem> -<para>to change user's password (or root's password)</para> - -</listitem> -</varlistentry> - -<varlistentry><term><command>man hier</></term> - -<listitem> -<para>man page on the Unix file system</para> - -</listitem> -</varlistentry> -</variablelist></para> - -<para>Use <command>find</> to locate filename in <filename>/usr</filename> -or any of its subdirectories with -<informalexample> -<screen>% <userinput>find /usr -name "<replaceable>filename</>"</></screen> -</informalexample> -You can use <literal>*</literal> as a wildcard in -<parameter>"<replaceable>filename</>"</> (which should be in -quotes). If you tell find to search in <filename>/</filename> -instead of <filename>/usr</filename> it will look for the file(s) on -all mounted file systems, including the CDROM and the dos -partition.</para> - -<para>An excellent book that explains Unix commands and utilities is -Abrahams & Larson, <citetitle>Unix for the Impatient</citetitle> -(2nd ed., Addison-Wesley, 1996). There's also a lot of Unix -information on the Internet. Try the <ulink -URL="http://www.eecs.nwu.edu/unix.html">Unix Reference -Desk</ulink>.</para> - -</chapter> - -<chapter> -<title>Next Steps</title> - -<para>You should now have the tools you need to get around and edit -files, so you can get everything up and running. There is a great -deal of information in the FreeBSD handbook (which is probably on -your hard drive) and <ulink URL="http://www.freebsd.org/">FreeBSD's -web site</ulink>. A wide variety of packages and ports are on the -<ulink URL="http://www.cdrom.com/">Walnut Creek</ulink> CDROM as well -as the web site. The handbook tells you more about how to use them -(get the package if it exists, with <command>pkg_add -/cdrom/packages/All/<replaceable>packagename</></>, -where <replaceable>packagename</replaceable> is the filename of the -package). The cdrom has lists of the packages and ports with brief -descriptions in <filename>cdrom/packages/index</filename>, -<filename>cdrom/packages/index.txt</filename>, and -<filename>cdrom/ports/index</filename>, with fuller descriptions in -<filename>/cdrom/ports/*/*/pkg/DESCR</filename>, where the -<literal>*</literal>s represent subdirectories of kinds of programs -and program names respectively.</para> - -<para>If you find the handbook too sophisticated (what with -<command>lndir</> and all) on installing ports from the cdrom, -here's what usually works:</para> - -<para>Find the port you want, say <command>kermit</>. There will be -a directory for it on the cdrom. Copy the subdirectory to -<filename>/usr/local</filename> (a good place for software you add -that should be available to all users) with: -<informalexample> -<screen># <userinput>cp -R /cdrom/ports/comm/kermit /usr/local</></screen> -</informalexample> - -This should result in a <filename>/usr/local/kermit</filename> -subdirectory that has all the files that the -<command>kermit</command> subdirectory on the CDROM has.</para> - -<para>Next, create the directory <filename>/usr/ports/distfiles</filename> -if it doesn't already exist using <command>mkdir</>. Now check -check <filename>/cdrom/ports/distfiles</filename> for a -file with a name that indicates it's the port you want. Copy that -file to <filename>/usr/ports/distfiles</filename>; in recent versions -you can skip this step, as FreeBSD will do it for you. -In the case of <command>kermit</>, there is no -distfile.</para> - -<para>Then <command>cd</> to the subdirectory of -<filename>/usr/local/kermit</filename> that has the file -<filename>Makefile</>. Type -<informalexample> -<screen># <userinput>make all install</></screen> -</informalexample> -</para> - -<para>During this process the port will ftp to get any compressed -files it needs that it didn't find on the cdrom or in -<filename>/usr/ports/distfiles</filename>. If you don't have your -network running yet and there was no file for the port in -<filename>/cdrom/ports/distfiles</filename>, you will have to get -the distfile using another machine and copy it to -<filename>/usr/ports/distfiles</filename> from a floppy or your dos -partition. Read <filename>Makefile</> (with <command>cat</> or -<command>more</> or <command>view</>) to find out where to go (the -master distribution site) to get the file and what its name is. Its -name will be truncated when downloaded to DOS, and after you get it -into <filename>/usr/ports/distfiles</filename> you'll have to rename -it (with the <command>mv</> command) to its original name so it can -be found. (Use binary file transfers!) Then go back to -<filename>/usr/local/kermit</filename>, find the directory with -<filename>Makefile</>, and type <command>make all install</>.</para> - -<para>The other thing that happens when installing ports or packages -is that some other program is needed. If the installation stops with -a message <errorname>can't find unzip</errorname> or whatever, you -might need to install the package or port for unzip before you -continue.</para> - -<para>Once it's installed type <command>rehash</> to make FreeBSD -reread the files in the path so it knows what's there. (If you get a -lot of <errorname>path not found</> messages when you use -<command>whereis</> or which, you might want to make additions to the -list of directories in the path statement in -<filename>.cshrc</filename> in your home directory. The path -statement in Unix does the same kind of work it does in DOS, except -the current directory is not (by default) in the path for security -reasons; if the command you want is in the directory you're in, you -need to type <filename>./</filename> before the command to make it -work; no space after the slash.)</para> - -<para>You might want to get the most recent version of Netscape from -their <ulink URL="ftp://ftp.netscape.com">ftp site</ulink>. (Netscape -requires the X Window System.) There's now a FreeBSD version, so look -around carefully. Just use <command>gunzip -<replaceable>filename</></> and <command>tar xvf -<replaceable>filename</></> on it, move the binary to -<filename>/usr/local/bin</filename> or some other place binaries are -kept, <command>rehash</>, and then put the following lines in -<filename>.cshrc</filename> in each user's home directory or (easier) -in <filename>/etc/csh.cshrc</filename>, the system-wide csh start-up -file: -<informalexample> -<programlisting>setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls</> -</informalexample> -This assumes that the file <filename>XKeysymDB</> and the directory -<filename>nls</> are in <filename>/usr/X11R6/lib/X11</filename>; if -they're not, find them and put them there.</para> - -<para>If you originally got Netscape as a port using the CDROM (or -ftp), don't replace <filename>/usr/local/bin/netscape</filename> with -the new netscape binary; this is just a shell script that sets up the -environmental variables for you. Instead rename the new binary to -<filename>netscape.bin</filename> and replace the old binary, which -is <filename>/usr/local/lib/netscape/netscape.bin</filename>.</para> - -</chapter> - -<chapter> - -<title>Your Working Environment</title> - -<para>Your shell is the most important part of your working environment. -In DOS, the usual shell is command.com. The shell is what interprets -the commands you type on the command line, and thus communicates with -the rest of the operating system. You can also write shell -scripts, which are like DOS batch files: a series of commands to be -run without your intervention.</para> - -<para>Two shells come installed with FreeBSD: csh and sh. csh is good for -command-line work, but scripts should be written with sh (or bash). You can -find out what shell you have by typing <command>echo $SHELL</command>.</para> - -<para>The csh shell is okay, but tcsh does everything csh does and more. It -It allows you to recall commands with the arrow keys and edit them. -It has tab-key completion -of filenames (csh uses the escape key), and it lets you switch to the -directory you were last in with <command>cd -</command>. It's also much -easier to alter your prompt with tcsh. It makes life a lot easier.</para> - -<para>Here are the three steps for installing a new shell:</para> - -<para> 1. Install the shell as a port or a package, just as you -would any other port or package. Use <command>rehash</command> and -<command>which tcsh</command> (assuming you're installing tcsh) to -make sure it got installed.</para> - -<para> 2. As root, edit <filename>/etc/shells</filename>, adding -a line in the file for the new shell, in this case /usr/local/bin/tcsh, -and save the file. (Some ports may do this for you.)</para> - -<para> 3. Use the <command>chsh</command> command to change your shell to -tcsh permanently, or type <command>tcsh</command> at the prompt to -change your shell without logging in again.</para> - -<para><emphasis>Note: It can be dangerous to change root's shell</emphasis> -to something other than sh or csh on early versions of FreeBSD and many -other versions of Unix; you may not have a working shell when the system -puts you into single user mode. The solution is to use <command>su -m</command> -to become root, which will give you the tcsh as root, because the shell is part -of the environment. You can make this permanent by adding it to your -<filename>.tcshrc</filename> file as an alias with <programlisting>alias su su -m.</></para> - -<para>When tcsh starts up, it will read the -<filename>/etc/csh.cshrc</filename> and <filename>/etc/csh.login</filename> -files, as does csh. It will also read the -<filename>.login</filename> file in your home directory and the -<filename>.cshrc</filename> -file as well, unless you provide a <filename>.tcshrc</filename> -file. This you can do by simply copying <filename>.cshrc</filename> -to <filename>.tcshrc</filename>.</para> - -<para>Now that you've installed tcsh, you can adjust your prompt. You can -find the details in the manual page for tcsh, but here is a line to -put in your <filename>.tcshrc</filename> that will tell you how many -commands you have typed, what time it is, and what directory you are in. -It also produces a <literal>></literal> if you're an ordinary user and -a <literal>#</literal> if you're root, but tsch will do that in any -case:</para> -<para> - set prompt = "%h %t %~ %# "</para> - -<para>This should go in the same place as the existing set prompt line -if there is one, or under "if($?prompt) then" if not. -Comment out the old line; you can always switch back to it if you prefer -it. Don't forget the spaces and quotes. You can get the <filename>.tcshrc</filename> reread by typing <command>source .tcshrc</command>.</para> - -<para>You can get a listing of other environmental variables that -have been set by typing <command>env</command> at the prompt. The -result will show you your default editor, pager, and terminal type, -among possibly many others. A useful command if you log in from a -remote location and can't run a program because the terminal isn't -capable is -<command>setenv TERM vt100</command>.</para> -</chapter> - - -<chapter> -<title>Other</title> - -<para>As root, you can dismount the CDROM with <command>/sbin/umount -/cdrom</>, take it out of the drive, insert another one, and mount it -with <command>/sbin/mount_cd9660 /dev/cd0a /cdrom</> assuming -<hardware>cd0a</> is the device name for your CDROM drive. The -most recent versions of FreeBSD let you mount the cdrom with just -<command>/sbin/mount /cdrom</command>.</para> - -<para>Using the live file system—the second of FreeBSD's CDROM -disks—is useful if you've got limited space. What is on the -live file system varies from release to release. You might try -playing games from the cdrom. This -involves using <command>lndir</>, which gets installed with the X -Window System, to tell the program(s) where to find the necessary -files, because they're in the <filename>/cdrom</filename> file system -instead of in <filename>/usr</filename> and its subdirectories, which -is where they're expected to be. Read <command>man lndir</>.</para> - -</chapter> - -<chapter> -<title>Comments Welcome</title> - -<para>If you use this guide I'd be interested in knowing where it was -unclear and what was left out that you think should be included, and -if it was helpful. My thanks to Eugene W. Stark, professor of -computer science at SUNY-Stony Brook, and John Fieber for helpful -comments.</para> - -<para>Annelise Anderson, <email>andrsn@andrsn.stanford.edu</></para> - -</chapter> -</book> diff --git a/en/tutorials/ppp/Makefile b/en/tutorials/ppp/Makefile deleted file mode 100644 index 76ead715ae..0000000000 --- a/en/tutorials/ppp/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.2 1997-07-01 05:38:16 max Exp $ - -DOC= ppp -SRCS= ppp.sgml - -.include <bsd.sgml.mk> diff --git a/en/tutorials/ppp/ppp.sgml b/en/tutorials/ppp/ppp.sgml deleted file mode 100644 index fc08b83f1c..0000000000 --- a/en/tutorials/ppp/ppp.sgml +++ /dev/null @@ -1,1734 +0,0 @@ -<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> -<!-- $Id: ppp.sgml,v 1.6 1998-04-21 00:47:14 eivind Exp $ --> - -<article> - -<title>PPP - Pedantic PPP Primer -<author>Maintainer: Steve Sims <tt><htmlurl -url="mailto:SimsS@IBM.NET" - name="<SimsS@IBM.NET>"></tt> - -<date>$Date: 1998-04-21 00:47:14 $ -<abstract> -This is a step-by-step guide for configuring FreeBSD systems to act as -a dial-up router/gateway in a Local Area Environment. All entries may -be assumed to be relevant to FreeBSD 2.2+, unless otherwise noted. -</abstract> - -<toc> - -<sect> -<heading>Overview:</heading> -<p>The User-Mode PPP dialer in FreeBSD Version 2.2 (also known as: -<it>"IIJ-PPP"</it> ) now supports Packet Aliasing for dial up -connections to the Internet. This feature, also known as -"<IT/Masquerading/", "<IT/IP Aliasing/", or "<IT/Network Address -Translation/", allows a FreeBSD system to act as a dial- on-demand -router between an Ethernet-based Local Area Network and an Internet -Service Provider. Systems on the LAN can use the FreeBSD system to -forward information between the Internet by means of a single -dial-connection. - -<sect1> -<heading>Purpose of this Guide.</heading> -<p> -This guide explains how to: -<itemize> -<item>Configure the FreeBSD system to support dial-out connections, -<item>Share a dial-out connection with other systems in a network, -<item>Configure Windows platforms to use the FreeBSD system as a gateway to the Internet. -</itemize> -<p> -While the focus of this guide is to assist in configuring IP Aliasing, -it also includes specific examples of the configuration steps necessary -to configure and install each individual component; each section stands -alone and may be used to assist in the configuration of various aspects -of FreeBSD internetworking. -</sect> - -<sect> -<heading>Building the Local Area Network</heading> - -<p> While the ppp program can, and usually is, be configured to provide -services to <em/only/ the local FreeBSD box it can also be used to serve as a -"Gateway" (or "router") between other LAN-connected resources and the Internet or -other Dial-Up service. - -<sect1> -<heading>Typical Network Topology</heading> - -<p>This guide assumes a typical Local Area Network lashed together as -follows: -<verb> -+---------+ ----> Dial-Up Internet Connection -| FreeBSD | \ (i.e.: NetCom, AOL, AT&T, EarthLink, -etc) -| |-------- -| "Curly" | -| | -+----+----+ - | -|----+-------------+-------------+----| <-- Ethernet Network - | | | - | | | -+----+----+ +----+----+ +----+----+ -| | | | | | -| Win95 | | WFW | | WinNT | -| "Larry" | | "Moe" | | "Shemp" | -| | | | | | -+---------+ +---------+ +---------+ -</verb> - -<sect1> -<heading>Assumptions about the Local Area Network</heading> - -<p>Some specific assumptions about this sample network are: - -<p>Three workstations and a Server are connected with Ethernet -cabling: -<itemize> -<item>a FreeBSD Server ("Curly") with an NE-2000 adapter configured as -'ed0' -<item>a Windows-95 workstation ("Larry") with Microsoft's "native" -32-bit TCP/IP drivers -<item>a Windows for Workgroups workstation ("Moe") with Microsoft's -16-bit TCP/IP extensions -<item>a Windows NT workstation ("Shemp") with Microsoft's "native" -32-bit TCP/IP drivers -</itemize> - -<p>The IP Addresses on the Ethernet side of this sample LAN have been - -taken from the pool of "reserved" addresses proposed in RFC-1597. -IP addresses are assigned as follows: -<verb>Name IP Address -"Curly" 192.168.1.1 # The FreeBSD box -"Larry" 192.168.1.2 # The Win'95 box -"Moe" 192.168.1.3 # The WfW box -"Shemp" 192.168.1.4 # The Windows NT box -</VERB> - -<p>This guide assumes that the modem on the FreeBSD box is connected -to the first serial port ('<tt>/dev/cuaa0</tt>' or '<tt>COM1:</tt>' in -DOS-terms). - -<p>Finally, we'll also assume that your Internet Service Provider (ISP) -automatically provides the IP addresses of both your PPP/FreeBSD side -as well as the ISP's side. (i.e.: Dynamic IP Addresses on both ends -of the link.) Specific details for configuring the Dial-Out side of -PPP will be addressed in Section 2, "Configuring the FreeBSD System". -</sect> - -<sect> -<heading>FreeBSD System Configuration</heading> - -<p>There are three basic pieces of information that must be known to -the FreeBSD box before you can proceed with integrating the sample -Local Area Network: - -<itemize> -<item>The Host Name of the FreeBSD system; in our example it's "Curly", -<item>The Network configuration, -<item>The <tt>/etc/hosts</tt> file (which lists the names and IP addresses of -the other systems in your network) -</itemize> - -<p>If you performed the installation of FreeBSD over a network -connection some of this information may already be configured into -your FreeBSD system. - -<p>Even if you believe that the FreeBSD system was properly configured -when it was installed you should at least verify each of these bits of -information to prevent trouble in subsequent steps. - -<sect1> -<heading>Verifying the FreeBSD Host Name</heading> - -<p>It's possible that the FreeBSD host name was specified and saved -when the system was initially installed. To verify that it was, enter -the following command at a prompt:<p> -<tscreen><verb> -# hostname -</verb></tscreen> - -<p>The name of the host FreeBSD system will be displayed on a single -line. If the name looks correct (this is very subjective :-) skip -ahead to Section 3.2, "Verifying the Ethernet Interface -Configuration". - -<p>For example, in our sample network, we would see 'curly.my.domain' -as a result of the `hostname` command if the name had been set -correctly during, or after, installation. (At this point, don't worry -too much about the ".my.domain" part, we'll sort this out later. The -important part is the name up to the first dot.) - -<p>If a host name wasn't specified when FreeBSD was installed you'll -probably see 'myname.my.domain` as a response. You'll need to edit -<tt>/etc/rc.conf</tt> to set the name of the machine. - -<sect2><heading>Configuring the FreeBSD Host Name</heading> - -<p><em><bf>Reminder: You must be logged in as 'root' to edit the -system configuration files!</bf></em> - -<em><bf>CAUTION: If you mangle the system configuration files, -chances are your system WILL NOT BOOT correctly! Be careful!</bf></em> - -<p>The configuration file that specifies the FreeBSD system's host -name when the system boots is in <tt>/etc/rc.conf</tt>. Use the -default text editor ('<tt/ee/') to edit this file. - -<p>Logged in as user 'root' load <tt>/etc/rc.conf</tt> into the -editor with the following command: -<tscreen><verb> -# ee /etc/rc.conf -</verb></tscreen> - -<p>Using the arrow keys, scroll down until you find the line that -specifies the host name of the FreeBSD system. By default, this -section says: -<tscreen><verb> ---- -### Basic network options: ### -hostname="myname.my.domain" # Set this! ---- -</verb></tscreen> -Change this section to say (in our example): -<tscreen><verb> ---- -### Basic network options: ### -hostname="curly.my.domain" # Set this! ---- -</verb></tscreen> - -Once the change to the host name has been made, press the 'Esc' key to -access the command menu. Select "leave editor" and make sure to -specify "save changes" when prompted. - -<sect1> -<heading>Verifying the Ethernet Interface Configuration</heading> - -<p>To reiterate our basic assumption, this guide assumes that the -Ethernet Interface in the FreeBSD system is named '<tt/ed0/'. This is -the default for NE-1000, NE-2000, WD/SMC models 8003, 8013 and Elite -Ultra (8216) network adapters. - -<p>Other models of network adapters may have different device names in -FreeBSD. Check the FAQ for specifics about your network adapter. If -you're not sure of the device name of your adapter, check the FreeBSD -FAQ to determine the device name for the card you have and substitute -that name (i.e.: '<tt/de0/', '<tt/zp0/', or similar) in the following -steps. - -<p>As was the case with the host name, the configuration for the -FreeBSD system's Ethernet Interface may have been specified when the -system was installed. - -To display the configuration for the interfaces in your -FreeBSD system (Ethernet and others), enter the following command: -<tscreen><verb> -# ifconfig -a -</verb></tscreen> -(In layman's terms: "Show me the <BF/I/nter<BF/F/ace <BF/CONFIG/uration -for my network devices.") - -<p>An example: -<tscreen><verb> -# ifconfig -a - ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu -1500 - inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255 - ether 01:02:03:04:05:06 - lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 - tun0: flags=8050<POINTOPOINT,RUNNING, MULTICAST> mtu 1500 - sl0: flags=c010<POINTOPOINT,LINK2,MULTICAST> mtu 552 - ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 - lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 - inet 127.0.0.1 netmask 0xff000000 -# _ -</verb></tscreen> - -<p>In this example, the following devices were displayed:<p> -<tt/ed0:/ The Ethernet Interface<p> -<tt/lp0:/ The Parallel Port Interface (ignored in this guide)<p> -<tt/tun0:/ The "tunnel" device; <em/This is the one user-mode ppp uses!/<p> -<tt/sl0:/ The SL/IP device (ignored in this guide)<p> -<tt/ppp0:/ Another PPP device (for kernel ppp; ignored in this guide)<p> -<tt/lo0:/ The "Loopback" device (ignored in this guide)<p> - -In this example, the 'ed0' device is up and running. The key -indicators are: -<enum> -<item>Its status is "<tt/UP/", -<item>It has an Internet ("<tt/inet/") address, (in this case, 192.168.1.1) -<item>It has a valid Subnet Mask ("netmask"; 0xffffff00 is the same as -255.255.255.0), and -<item>It has a valid broadcast address (in this case, 192.168.1.255). -</enum> - -<p>If the line for the Ethernet card had shown something similar to: -<tscreen><verb> -ed0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> mtu 1500 - ether 01:02:03:04:05:06 -</verb></tscreen> -then the Ethernet card hasn't been configured yet. - -<p>If the configuration for the Ethernet interface is correct you can -skip forward to Section 3.4, "Creating the list of other LAN hosts". -Otherwise, proceed with the next section. -<sect2> -<heading>Configuring your Ethernet Interface</heading> - -<p><em><bf>Reminder: You must be logged in as 'root' to edit the -system configuration files!</bf></em> - -<em><bf>CAUTION: If you mangle the system configuration files, -chances are your system WILL NOT BOOT correctly! Be careful!</bf></em> - -<p>The configuration file that specifies settings for the network -interfaces when the system boots is in <tt>/etc/rc.conf</tt>. Use -the default text editor ('ee') to edit this file. - -<p>Logged in as user 'root' load <tt>/etc/rc.conf</tt> into the -editor with the following command: -<p> -<tt> # ee /etc/rc.conf</tt> -<p> -About 20 lines from the top of <tt>/etc/rc.conf</tt> is the section -that describes which network interfaces should be activated when the -system boots. In the default configuration file the specific line -that controls this is: - -<tscreen><verb> -network_interfaces="lo0" # List of network interfaces (lo0 is loopback). -</verb></tscreen> - -<p>You'll need to amend this line to tell FreeBSD that you want to add -another device, namely the '<tt/ed0/' device. Change this line to -read: - -<tscreen><verb> -network_interfaces="lo0 ed0" # List of network interfaces (lo0 is loopback). -</verb></tscreen> - -<p>(Note the space between the definition for the loopback device -("<tt/lo0/") -and the Ethernet device ("<tt/ed0/")! - -<p><em><bf> Reminder: If your Ethernet card isn't named '<tt/ed0/', specify -the correct device name here instead.</bf></em> - -<p>If you performed the installation of FreeBSD over a network -connection then the '<tt/network_interfaces=/' line may already -include a reference to your Ethernet adapter. If it is, verify that -it is the correct device name. - -<p>Specify the Interface Settings for the Ethernet device -('<tt/ed0/'): - -<p>Beneath the line that specifies which interfaces should be -activated are the lines that specify the actual settings for each -interface. In the default <tt>/etc/rc.conf</tt> file is a single -line that says: - -<tscreen><verb> -ifconfig_lo0="inet 127.0.0.1" # default loopback device configuration. -</verb></tscreen> - -<p>You'll need to add another line after that to specify the settings -for your '<tt/ed0/' device. - -<p>If you performed the installation of FreeBSD over a network -connection then there may already be an '<tt>ifconfig_ed0=</tt>' line -after the loopback definition. If so, verify that it has the correct -values. - -<p>For our sample configuration we'll insert a line immediately after -the loopback device definition that says: - -<tscreen><verb> -ifconfig_ed0="inet 192.168.1.1 netmask 255.255.255.0" -</verb></tscreen> - -<p>When you've finished editing <tt>/etc/rc.conf</tt> to specify and -configure the network interfaces the section should look really close -to: - -<tscreen><verb> ---- -network_interfaces="ed1 lo0" # List of network interfaces (lo0 is loopback). -ifconfig_lo0="inet 127.0.0.1" # default loopback device configuration. -ifconfig_ed1="inet 192.168.1.1 netmask 255.255.255.0" ---- -</verb></tscreen> - -<p>Once all of the necessary changes to <tt>/etc/rc.conf</tt> have -been made, press the 'Esc' key to invoke the control menu. Select -"leave editor" and be sure to select "save changes" when prompted. - -<sect1> -<heading>Enabling Packet Forwarding</heading> - -<p>By default the FreeBSD system will not forward IP packets between -various network interfaces. In other words, routing functions (also -known as gateway functions) are disabled. - -<p>If your intent is to use a FreeBSD system as stand-alone Internet -workstation and not as a gateway between LAN nodes and your ISP you -should skip forward to Section 3.4, "Creating the List of Other -LAN Hosts". - -<p>If you intend for the PPP program to service the local FreeBSD box -as well as LAN workstations (as a router) you'll need to enable IP -forwarding. - -<p>To enable IP Packet forwarding you'll need to edit the -<tt>/etc/rc.conf</tt> file. -Load this file into your editor with the following command: -<tscreen><verb> -# ee /etc/rc.conf -</verb></tscreen> - -<p>About 85 lines down from the top of the file will be the -configuration -section which controls IP forwarding, which will look like: -<tscreen><verb> -===== -gateway_enable="NO" # Set to YES if this host will be a gateway. -===== -</verb></tscreen> - -<p>Change this line to read: -<tscreen><verb> -===== -gateway_enable="YES" # Set to YES if this host will be a gateway. -===== -</verb></tscreen> - -and exit the editor (saving the changes!). - -<p><em><bf>NOTE: This line may already be set to -'<tt/gateway_enable="YES"/' if IP forwarding was enabled when the -FreeBSD system was installed.</bf></em> - -<sect1> -<heading>Creating the List of other LAN Hosts(<tt>/etc/hosts</tt>)</heading> - -<p>The final step in configuring the LAN side of the FreeBSD system is -to create a list of the names and TCP/IP addresses of the various -systems that are connected to the Local Area Network. This list is -stored in the '<tt>/etc/hosts</tt>' file. - -<p>The default version of this file has only a single host name -listing in it: the name and address of the loopback device ('lo0'). -By networking convention, this device is always named "localhost" and -always has an IP address of 127.0.0.1. (See the interface -configuration example in Section 3.2.) - -<p>To edit the <tt>/etc/hosts</tt> file enter the following command: -<tscreen><verb> # ee /etc/hosts </verb></tscreen> - -<p>Scroll all the way to the bottom of the file (paying attention to -the comments along the way; there's some good information there!) and -enter (assuming our sample network) the following IP addresses and -host names: -<tscreen><verb> -192.168.1.1 curly curly.my.domain # FreeBSD System -192.168.1.2 larry larry.my.domain # Windows '95 System -192.168.1.3 moe moe.my.domain # Windows for Workgroups -System -192.168.1.4 shemp shemp.my.domain # Windows NT System -</verb></tscreen> - -<p>(No changes are needed to the line for the '<tt>127.0.0.1 -localhost</tt>' entry.) - -<p>Once you've entered these lines, press the 'Esc' key to invoke the -control menu. Select "leave editor" and be sure to select "save -changes" when prompted. - -<sect1> -<heading>Testing the FreeBSD system</heading> - -<p>Congratulations! Once you've made it to this point, the FreeBSD -system is configured as a network-connected UNIX system! If you made -any changes to the <tt>/etc/rc.conf</tt> file you should probably -re-boot your FreeBSD system. This will accomplish two important -objectives: -<itemize> -<item>Allow the changes to the interface configurations to be applied, and -<item>Verify that the system restarts without any glaring configuration errors. -</itemize> - -Once the system has been rebooted you should test the network -interfaces. -<p> -<sect2> -<heading>Verifying the operation of the loopback device</heading> - -<p>To verify that the loopback device is configured correctly, log in as -'root' and enter: -<tscreen><verb> -# ping localhost -</verb></tscreen> - -<p>You should see: -<tscreen><verb> -# ping localhost -PING localhost.my.domain. (127.0.0.1): 56 data bytes -64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=0.219 ms -64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=0.287 ms -64 bytes from 127.0.0.1: icmp_seq=2 ttl=255 time=0.214 m -[...] -</verb></tscreen> -messages scroll by until you hit Ctrl-C to stop the madness. - -<sect2> -<heading>Verifying the operation of the Ethernet Device</heading> - -<p>To verify that the Ethernet device is configured correctly, enter: - -<tscreen><verb> -# ping curly -</verb></tscreen> - -You should see: -<tscreen><verb> -# ping curly -PING curly.my.domain. (192.168.1.1): 56 data bytes -64 bytes from 192.168.1.1: icmp_seq=0 ttl=255 time=0.219 ms -64 bytes from 192.168.1.1: icmp_seq=1 ttl=255 time=0.200 ms -64 bytes from 192.168.1.1: icmp_seq=2 ttl=255 time=0.187 ms -[...] -</verb></tscreen> -messages. - -<p>One important thing to look at in these two examples is that the -names (loopback and curly) correctly correlate to their IP addresses -(127.0.0.1 and 192.168.1.1). This verifies that the -<tt>/etc/hosts</tt> files is correct. - -<p>If the IP address for "curly" isn't 192.168.1.1 or the address for -"localhost" isn't 127.0.0.1, return to Section 3.4 and review your -entries in '<tt>/etc/hosts</tt>'. - -<p>If the names and addresses are indicated correctly in the result of -the ping command but there are errors displayed then something is -amiss with the interface configuration(s). Return to Section 3.1 and -verify everything again. - -<p>If everything here checks out, proceed with the next section. -</sect> - -<sect> -<heading>Configuring the PPP Dial-Out Connection</heading> -<p>There are two basic modes of operation of the ppp driver: -"Interactive" and "Automatic". - -In Interactive mode you:<p> -<itemize> -<item>Manually establish a connection to your ISP, -<item>Browse, surf, transfer files and mail, etc..., -<item>Manually disconnect from your ISP. -</itemize> - -<p>In Automatic mode, the PPP program silently watches what goes on -inside the FreeBSD system and automagically connects and disconnects -with your ISP as required to make the Internet a seamless element of -your network. - -<p>In this section we'll address the configuration(s) for both modes -with emphasis on configuring your `ppp` environment to operate in -"Automatic" mode. - -<sect1> -<heading>Backing up the original PPP configuration files</heading> - -<p>Before making any changes to the files which are used by PPP you -should make a copy of the default files that were created when the -FreeBSD system was installed. - -Log in as the 'root' user and perform the following steps: - -Change to the '<tt>/etc</tt> directory: -<p><tt># cd /etc</tt> - -Make a backup copy the original files in the 'ppp' directory: -<p><tt># cp -R ppp ppp.ORIGINAL</TT> - -<p>You should now be able to see both a '<tt>ppp</tt>' and a -'<tt>ppp.ORIGINAL</tt>' subdirectory -in the '<tt>/etc</tt>' directory. - -<sect1> -<heading>Create your own PPP configuration files</heading> - -<p>By default, the FreeBSD installation process creates a number of -sample configuration files in the /etc/ppp directory. Please take -some time to review these files; they were derived from working -systems and represent the features and capabilities of the PPP -program. - -<p>I <em/strongly/ encourage you to learn from these sample files and -apply them to your own configuration as necessary. - -<p>For detailed information about the `ppp` program, read the ppp -manpage: -<tscreen><verb> -# man ppp -</verb></tscreen> - -<p>For detailed information about the `chat` scripting language used by -the PPP dialer, read the chat manpage: -<tscreen><verb> -# man chat -</verb></tscreen> - -<p>The remainder of this section describes the recommended contents of -the PPP configuration files. - -<sect2> -<heading>The '<tt>/etc/ppp/ppp.conf</tt>' file</heading> - -<p>The '<tt>/etc/ppp/ppp.conf</tt>' file contains the information and -settings required to set up a dial-out PPP connection. More than one -configuration may be contained in this file. The FreeBSD handbook -(XXX URL? XXX) describes the contents and syntax of this file in -detail. - -<p>This section will describe only the minimal configuration to get a -dial-out connection working. - -<p>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a -dial-out Internet gateway for our example LAN: -<tscreen><verb> -################################################################ -# PPP Configuration File ('/etc/ppp/ppp.conf') -# -# Default settings; These are always executed always when PPP -# is invoked and apply to all system configurations. -################################################################ -default: -set device /dev/cuaa0 -set speed 57600 -disable pred1 -deny pred1 -disable lqr -deny lqr -set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 -OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" -set redial 3 10 -# -# -################################################################ -# -# For interactive mode use this configuration: -# -# Invoke with `ppp -alias interactive` -# -################################################################ -interactive: -set authname Your_User_ID_On_Remote_System -set authkey Your_Password_On_Remote_System -set phone 1-800-123-4567 -set timeout 300 -set openmode active -accept chap -# -################################################################ -# -# For demand-dial (automatic) mode we'll use this configuration: -# -# Invoke with: 'ppp -auto -alias demand' -# -################################################################ -demand: -set authname Your_User_ID_On_Remote_System -set authkey Your_Password_On_Remote_System -set phone 1-800-123-4567 -set timeout 300 -set openmode active -accept chap -set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 -add 0 0 127.2.2.2 -################################################################ -# End of /etc/ppp/ppp.conf -</verb></tscreen> -This file, taken verbatim from a working system, has three relevant -configuration sections: - -<sect3> -<heading>The "<tt>default</tt>" Section</heading> - -<p>The '<tt>default:</tt>' section contains the values and settings -used by every other section in the file. Essentially, this section is -implicitly added to the configuration lines to each other section. - -<p>This is a good place to put "global defaults" applicable to all -dial-up sessions; especially modem settings and dialing prefixes which -typically don't change based on which destination system you're -connecting to. - -<p>Following are the descriptions of each line in the "default" section -of the sample '<tt>/etc/ppp/ppp.conf</tt>' file: -<tscreen><verb> -set device /dev/cuaa0 -</verb></tscreen> -This statement informs the PPP program that it should use the first -serial port. -Under FreeBSD the '<tt>/dev/cuaa0</tt>' device is the same port that's -known as "<tt>COM1:</tt>" under DOS, Windows, Windows 95, etc.... - -<p>If your modem is on <tt>COM2:</tt> you should specify -'<tt>/dev/cua01</tt>; <tt>COM3:</tt> would be '<tt>/dev/cua02</tt>'. - -<tscreen><verb> -set speed 57600 -</verb></tscreen> - -This line sets the transmit and receive speed for the connection -between the serial port and the modem. While the modem used for this -configuration is only a 28.8 device, setting this value to 57600 lets -the serial link run at a higher rate to accommodate higher throughput -as a result of the data compression built into late-model modems. - -If you have trouble communicating with your modem, try setting this -value to 38400 or even as low as 19200. - -<tscreen><verb> -disable pred1 -deny pred1 -</verb></tscreen> - -These two lines disable the "CCP/Predictor type 1" compression -features of the PPP program. The current version of `ppp` supports -data compression in accordance with draft Internet standards. -Unfortunately many ISPs use equipment that does not support this -capability. Since most modems try to perform on-the-fly compression -anyway you're probably not losing much performance by disabling this -feature on the FreeBSD side and denying the remote side from forcing -it on you. - -<tscreen><verb> -disable lqr -deny lqr -</verb></tscreen> - -These two lines control the "Line Quality Reporting" functions which -are part of the complete Point-to-Point (PPP) protocol specification. -(See RFC-1989 for details.) - -The first line, "disable lqr", instructs the PPP program to not -attempt to report line quality status to the device on the remote end. - -The second line, "deny lqr", instructs the PPP program to deny any -attempts by the remote end to reports line quality. - -As most modern dial-up modems have automatic error correction and -detection and LQR reporting is not fully implemented in many vendor's -products it's generally a safe bet to include these two lines in the -default configuration. - -<tscreen><verb> -set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 -OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" -</verb></tscreen> - -<em>NOTE: (This statement should appear on a single line; ignore any -line wrapping that may appear in this document.)</em> - -This line instructs the PPP program how to dial the modem and -specifies some rudimentary guidelines for doing so: -<itemize> -<item>Attempts to dial should fail if the modem returns a "BUSY" result code, -<item>Attempts to dial should also fail if the modem returns a "NO CARRIER" result code, -<item>The PPP program should expect each of the following events to complete within a -5-second timeout period: -<itemize> -<item>The PPP program will initially expect nothing (specified above -by the \"\" portion of the statement) from the modem <item>The program -will send the modem initialization string "ATE1Q0M0" to the modem and -await a response of "OK". If a response is not received, the program -should send an attention command to the modem ("AT") and look again -for a response of "OK", <item>The program should delay for one second -(specified by the "\\d" part of the statement, and send the dialing -string to the modem. The "ATDT" portion of the statement is the -standard modem prefix to dial using tone-dialing; if you do not have -touch-tone service on your local phone line, replace the "ATDT" with -"ATDP". The "\\T" string is a placeholder for the actual phone number -(which will be automatically inserted as specified by the "set dial -123-4567"). -</itemize> -<item>Finally, before a (maximum) timeout of 40 seconds, the PPP -program should expect to see a "CONNECT" result code returned from the -modem. -</itemize> - -A failure at any point in this dialog will be interpreted as a dialing -failure and the PPP program will fail to connect. - -(For a detailed description of the mini-scripting language used by the -PPP dialer, refer to the "chat" manpage.) - -<tscreen><verb> -set redial 3 10 -</verb></tscreen> -This line specifies that if a dial connection cannot immediately be made -the PPP program should retry (up to 3 times if necessary) with a delay of 10 seconds -between redialing attempts. - -<sect3> -<heading>The "<tt>interactive</tt>" Section</heading> - -<p>The '<tt>interactive:</tt>' section contains the values and -settings used to set up an "interactive" PPP session with a specific -remote system. Settings in this section will have the lines included -in the "default" section included automatically. - -<p>The example cited in this section of the guide presumes that you'll -be connecting to a remote system that understands how to authenticate -a user without any fancy scripting language. That is, this sample -uses the CHAP protocol to set up the connection. - -<p>A good rule of thumb is that if the Windows '95 dialer can set up a -connection by just clicking the "Connect" button this sample -configuration should work OK. - -<p>If, on the other hand, when you connect to your ISP using Microsoft -Windows '95 Dial-Up Networking you need to resort to using the "Dial -Up Scripting Tool" from the Microsoft Plus! pack or you have to select -"Bring up a terminal windows after dialing" in the Windows '95 -connection options then you'll need to look at the sample PPP -configuration files and the ppp manpage for examples of "expect / -response" scripting to make your ISP connection. The "set login" -command is used for this purpose. - -<p>Or even better, find an ISP who knows how to provide PAP or CHAP -authentication! - -<p>The configuration examples shown here have been successfully used to -connect to: -<itemize> -<item>Various Shiva LanRovers -<item>The IBM Network (<url url="http://www.ibm.net">) -<item>AT&T WorldNet (<url url="http://att.com/worldnet">) -<item>Erol's (<url url="http://www.erols.com">) -</itemize> - -Following are descriptions for each line in the "interactive" section -of the sample '<tt>/etc/ppp/ppp.conf</tt>' file: - -<tscreen><verb> -set authname Your_User_ID_On_Remote_System -</verb></tscreen> -This line specifies the name you would use to log in to the remote -system. - -<tscreen><verb> -set authkey Your_Password_On_Remote_System -</verb></tscreen> -This is the password you'd use to log in to the remote system. - -<tscreen><verb> -set phone 1-800-123-4567 -</verb></tscreen> -This is the phone number of the remote system. If you're inside a PBX -you can -prepend '<tt>9, </tt>' to the number here. - -<tscreen><verb> -set timeout 300 -</verb></tscreen> -This tells the PPP program that it should automatically hang up the -phone if no data has -be exchanged for 300 seconds (5 minutes). You may wish to tailor this -number to your -specific requirements. - -<tscreen><verb> -set openmode active -</verb></tscreen> -This tells the PPP program that once the modems are connected it -should immediately attempt to negotiate the connection. Some remote -sites do this automatically, some don't. This instructs your side of -the link to take the initiative and try to set up the connection. - -<tscreen><verb> -accept chap -</verb></tscreen> -This tells the PPP program to use the "Challenge-Handshake -Authentication Protocol" to authenticate you. The values exchanged -between the local and remote side for UserID and password are taken -from the 'authname' and 'authkey' entries above. - -<sect3> -<heading>The "<tt>demand</tt>" Section</heading> - -<p>The "<tt>demand</tt>" section contains the values and settings used -to set up a "Dial-on-demand" PPP session with a specific remote -system. Settings in this section will also have the lines included in -the "default" section included automatically. - -<p>Except for the last two lines in this section it is identical to -the configuration section which defines the "interactive" -configuration. - -<p>As noted in Paragraph ???, the examples cited in this section of -the guide presume that you'll be connecting to a remote system that -understands how to use the CHAP protocol to set up the connection. - -<p>Following are descriptions for each line in the "demand" section of -the sample '<tt>/etc/ppp/ppp.conf</tt>' file: - -<tscreen><verb> -set authname Your_User_ID_On_Remote_System -</verb></tscreen> -This line specifies the name you would use to log in to the remote -system. - -<tscreen><verb> -set authkey Your_Password_On_Remote_System -</verb></tscreen> -This is the password you'd use to log in to the remote system. - -<tscreen><verb> -set phone 1-800-123-4567 -</verb></tscreen> -This is the phone number of the remote system. - -<tscreen><verb> -set timeout 300 -</verb></tscreen> - -This tells the PPP program that it should automatically hang up the -phone if no data has be exchanged for 300 seconds (5 minutes). You -may wish to tailor this number to your specific requirements. - -<tscreen><verb> -set openmode active -</verb></tscreen> - -This tells the PPP program that once the modems are connected it -should immediately attempt to negotiate the connection. Some remote -sites do this automatically, some don't. This instructs your side of -the link to take the initiative and try to set up the connection. - -<tscreen><verb> -accept chap -</verb></tscreen> - -This tells the PPP program to use the "Challenge-Handshake -Authentication Protocol" to authenticate you. The values exchanged -between the local and remote side for UserID and password are taken -from the 'authname' and 'authkey' entries above. - -<tscreen><verb> -set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 -</verb></tscreen> - -This command sets up a pair of "fake" IP addresses for the local and -remote sides of the PPP link. It instructs the PPP program to create -an IP address of 127.1.1.1 for the local side of the '<tt/tun0/' -(tunnel) device (refer back to section ?? for a description of this -device) and 127.2.2.2 for the remote side. Appending '<tt>/0</tt>' to -each address tells the PPP program that zero of the bits that make up -these addresses are significant and can (in fact, must!) be negotiated -between the local and remote systems when the link is established. -The 255.255.255.0 string tells the PPP program what Subnet mask to -apply to these pseudo-interfaces. - -<p>Remember, we've assumed that your ISP provides the IP addresses for -both ends of the link! If your ISP assigned you a specific IP address -that you should use on your side when configuring your system, enter -that IP address here <em/instead/ of <tt>127.1.1.1</tt>. - -Conversly, if your ISP gave you a specific IP address that he uses on -his end you should enter that IP address here <em/instead/ of -<tt>127.2.2.2</tt>. - -In both cases, it's probably a good idea to leave the '<tt>/0</tt>' on -the end of each address. This gives the PPP program the opportunity -to change the address(es) of the link if it <em/has/ to. - -<tscreen><verb> -add 0 0 127.2.2.2 -</verb></tscreen> - -This last line tells the PPP program that it should add a default -route for IP traffic that points to the (fake) IP address of the ISP's -system. - -<em><bf>Note: If you used an ISP-specified address instead of -<tt>127.2.2.2</tt> on the preceeding line, use the same number here -instead of <tt>127.2.2.2</tt></bf></em>. - -<p>By adding this "fake" route for IP traffic, the PPP program can, -while idle: -<itemize> -<item>Accept packets that FreeBSD doesn't already know how to forward, -<item>Establish a connection to the ISP "<em/on-the-fly/", -<item>Reconfigure the IP addresses of the local and remote side of the link, -<item>Forward packets between your workstation and the ISP. -</itemize> -automatically! - -<p>Once the number of seconds specified by the timeout value in the -"default" section have elapsed without any TCP/IP traffic the PPP -program will automatically close the dial-up connection and the -process will begin again. - -<sect2> -<heading>The '<tt>/etc/ppp/ppp.linkup</tt>' file</heading> - -<p>The other file needed to complete the PPP configuration is found in -'<tt>/etc/ppp/ppp.linkup</tt>'. This file contains instructions for -the PPP program on what actions to take after a dial-up link is -established. - -In the case of dial-on-demand configurations the PPP program will need -to delete the default route that was created to the fake IP address of -the remote side (127.2.2.2 in our example in the previous section) and -install a new default route that points the actual IP address of the -remote end (discovered during the dial-up connection setup). - -A representative '<tt>/etc/ppp/ppp.linkup</tt>' file: -<tscreen><verb> -#########################################################################= - -# PPP Link Up File ('/etc/ppp/ppp.linkup') -# -# This file is checked after PPP establishes a network connection. -# -# This file is searched in the following order. -# -# 1) First, the IP address assigned to us is searched and -# the associated command(s) are executed. -# -# 2) If the IP Address is not found, then the label name specified at - -# PPP startup time is searched and the associated command(s) -# are executed. -# -# 3) If neither of the above are found then commands under the label -# 'MYADDR:' are executed. -# -#########################################################################= - -# -# This section is used for the "demand" configuration in -# /etc/ppp/ppp.conf: -demand: - delete ALL - add 0 0 HISADDR -# -# All other configurations in /etc/ppp/ppp.conf use this: -# -MYADDR: - add 0 0 HISADDR -######################################################################## -# End of /etc/ppp/ppp.linkup -</verb></tscreen> -Notice that there is a section in this file named "demand:", identical -to the configuration name used in the '<tt>/etc/ppp/ppp.conf</tt>' -file. This section instructs the PPP program that once a link is -established using this configuration, it must: -<enum> - <item>Remove any IP routing information that the PPP program has created - <item>Add a default route the remote end's actual address. -</enum> - -<p>It's critical that those configurations in -'<tt>/etc/ppp/ppp.conf</tt>' which include the '<tt/set ifaddr/' and -'<tt/add 0 0/' statements (i.e.: those configurations used for -Dial-on-Demand configurations) execute the "delete ALL" and "add 0 0 -HISADDR" commands in <tt>/etc/ppp/ppp.linkup</tt>. - -<p><em><bf>This is the mechanism that controls the actual on-demand -configuration of the link.</bf></em> - -<p>All configurations not explicitly named in -<tt>/etc/ppp/ppp.linkup</tt> will use whatever commands are in the -"MYADDR:" section of the file. This is where non-Demand-Dial -configurations (such as our "interactive:" sample) will fall through -to. This section simply adds a default route to the ISP's IP address -(at the remote end). - -<sect1> -<heading>IP Aliasing</heading> - -<p>All of the configuration steps described thus far are relevant to -any FreeBSD system which will be used to connect to an ISP via dial-up -connection. - -<p>If your sole objective in reading this guide is to connect your -FreeBSD box to the Internet using dial-out ppp you can proceed to -Section 6, "Testing the Network". - -One very attractive feature of the PPP program in on-demand mode is -its ability to route IP traffic between other systems on the Local -Area Network automatically. This feature is known by various names, -"<em/IP Aliasing/", "<em/Network Address Translation/", "<em/Address -Masquerading/" or "<em/Transparent Proxying/". - -<p>Regardless of the terminology used, this mode is not, however, -automatic. If the PPP program is started normally then the program -will not forward packets between LAN interface(s) and the dial-out -connection. In effect, only the FreeBSD system is connected to the -ISP; other workstations cannot "share" the same connection. - -For example, if the program is started with either of the following -command lines: -<p><tt># ppp interactive (Interactive mode)</tt><p> or -<p><tt># ppp -auto demand (Dial-on-Demand mode)</tt> -<p>then the system will function as an Internet-connected workstation -<em/only/ for the -FreeBSD box. - -To start the PPP program as a gateway between LAN resources and the -Internet, one of the following command lines would be used instead: -<p><tt># ppp -alias interactive (Interactive mode)</tt><p> or -<p><tt># ppp -auto -alias demand (Dial-on-Demand mode)</tt> -<p>You can alternatively use the command <tt/``alias enable yes''/ -in your ppp configuration file (refer to the man page for details). -<p>Keep this in mind if you intend to proceed with Section 5, -"Configuring Windows Systems". -</sect> - -<sect> -<heading>Configuring Windows Systems</heading> - -<p>As indicated in Section 1, our example network consists of a -FreeBSD system ("Curly") which acts as a gateway (or router) between a -Local Area Network consisting of two different flavors of Windows -Workstations. In order for the LAN nodes to use Curly as a router -they need to be properly configured. Note that this section does not -explain how to configure the Windows workstations for Dial-Up -networking. If you need a good explanation of that procedure, I -recommend <url url="http://www.aladdin.co.uk/techweb">. - -<sect1> -<heading> Configuring Windows 95</heading> - -<p>Configuring Windows 95 to act as an attached resource on your LAN -is relatively simple. The Windows 95 network configuration must be -slightly modified to use the FreeBSD system as the default gateway to -the ISP. Perform the following steps: - -<p><bf>Create the Windows 95 "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4. -<itemize> -<item>Click the "Start" button; select "Run..."; enter "notepad -\WINDOWS\HOSTS" (without the quotes) and click "OK" -<item>In the editor, enter the addresses and system names from the hosts -file shown in Section 3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows 95 TCP/IP Network Configuation -settings</bf>: -<itemize> -<item>Click the "Start" button on the taskbar; select "Settings" and -"Control Panel". -<item>Double-click the "Network" icon to open it.<p> -The settings for all Network Elements are displayed. -<item>With the "Configuration" tab selected, scroll down the list of -installed components and highlight the "TCP/IP-><em/YourInterfaceType/" line -(where "<em/YourInterfaceType/" is the name or type of Ethernet adapter in your system). -<p>If TCP/IP is not listed in the list of installed network -components, click the "Add" button and install it before proceeding. -<p>(Hint: "Add | Protocol | Microsoft | TCP/IP | OK") -<item>Click on the "Properties" button to display a list of the -settings associated with the TCP component. -</itemize> - -<p><bf>Configure the IP Address Information:</bf> -<itemize> -<item>Click the "IP Address" tab -<item>Click the "Specify an IP address" radio button. - <p>(In our example LAN the Windows 95 system is the one we've called "Larry".) -<item>In the "IP Address" field enter "192.168.1.2". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> -<itemize> -<item>Click on the "Gateway" tab -<p>For our example network the FreeBSD box will be acting as our -gateway to the Internet (routing packets between the Ethernet LAN and -the PPP dial-up connection. Enter the IP address of the FreeBSD -Ethernet interface, 192.168.1.1, in the "New gateway" field and click -the "Add" button. If any other gateways are defined in the "Installed -gateways" list you may wish to consider removing them. -</itemize> - -<p><bf>Configure the DNS Information:</bf> - -<p>This guide assumes that your Internet Service Provider has given -you a list of Domain Name Servers (or "DNS Servers") that you should -use. If you wish to run a DNS server on your local FreeBSD system, -refer to Section 6, "Exercise for the Interested Student" for tips on -setting up DNS on your FreeBSD system. - -<itemize> -<item>Click the "DNS Configuration" tab -<item>Make sure that the "Enable DNS" radio button is selected. -<p>(If this button is not selected only the entries that -we put in the host file(s) will be available and your Net-Surfing -will not work as you expect!) -<item>In the "Host" field enter the name of the Windows 95 box, in this -case: "Larry". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "DNS Server Search Order" section, enter the IP address -of the DNS server(s) that your ISP provided, clicking the "Add" button -after every address is entered. Repeat this step as many times as -necessary to add all of the addresses that your ISP provided. -</itemize> - -<p><bf>Other Windows 95 TCP/IP options:</bf> - -<p>For our purposes the settings under the "Advanced", "WINS -Configuration" and "Bindings" tabs are not necessary. - -<p>If you wish to use the Windows Internet Naming Service ("WINS") -your attention is invited to <url url="http://www.localnet.org"> for -more information about WINS settings, specifically regarding sharing -files transparently across the Internet. - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Properties window. -<item>Click on the "OK" button to close the Network Control Panel. -<item>Reboot your computer if prompted to do so. -</itemize> - -<p> That's it! -<sect1> -<heading>Configuring Windows NT</heading> - -<p>Configuring Windows NT to act as a LAN resource is also relatively -straightforward. The procedures for configuring Windows NT are -similar to Windows 95 with minor exceptions in the user interface. - -<p>The steps shown here are appropriate for a Windows NT 4.0 -Workstation, but the principles are the same for NT 3.5x. You may -wish to refer to the "Configuring Windows for Workgroups" section if -you're configuring Windows NT 3.5<it/x/, since the user interface is -the same for NT 3.5 and WfW. - -<p>Perform the following steps: - -<p><bf>Create the Windows NT "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4 -<itemize> -<item>Click the "Start" button; select "Run..."; enter "notepad -\WINDOWS\SYSTEM\DRIVERS\ETC\HOSTS" (without the quotes) and click -"OK" -<item>In the editor, enter the addresses and system names from Section -3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows NT TCP/IP Network Configuation -settings</bf>: -<itemize> -<item>Click the "Start" button on the taskbar; select "Settings" and -"Control Panel". -<item>Double-click the "Network" icon to open it. -<item>With the "Identification" tab selected, verify the "Computer Name" -and "Workgroup" fields. In this example we'll use "Shemp" for the name -and "Stooges" for the workgroup. Click the "Change" button and amend -these entries as necessary. -<item>Select the "Protocols" tab. - -<p>The installed Network Protocols will be displayed. There may be a -number of protocols listed but the one of interest to this guide is -the "TCP/IP Protocol". If "TCP/IP Protocol" is not listed, click the -"Add" button to load it. -<p>(Hint: "Add | TCP/IP Protocol | OK") <item>Highlight "TCP/IP -Protocol" and click the "Properties" button. -<p>Tabs for specifying various settings for TCP/IP will be displayed. - </itemize> - -<p><bf>Configuring the IP Address:</bf> - -<p>Make sure that the Ethernet Interface is shown in the "Adapter" -box; if not, scroll through the list of adapters until the correct -interface is shown. -<itemize> -<item>Click the "Specify an IP address" radio button to enable the three -text boxes. -<p>In our example LAN the Windows NT system is the one we've called -"Shemp" -<item>In the "IP Address" field enter "192.168.1.4". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> - -<p>For our example network the FreeBSD box will be acting as our gateway -to the Internet (routing packets between the Ethernet LAN and the PPP dial-up -connection. -<itemize> -<item>Enter the IP address of the FreeBSD Ethernet interface, -192.168.1.1, in the "New gateway" field and click the "Add" button. -<p>If any other gateways are defined in the "Installed gateways" list -you may wish to consider removing them. -</itemize> -<p><bf>Configuring DNS:</bf> -<p>Again, this guide assumes that your Internet Service Provider has -given you a list of Domain Name Servers (or "DNS Servers") that you -should use. - -If you wish to run a DNS server on your local FreeBSD system, refer to -Section 6, "Exercise for the Interested Student" for tips on setting -up DNS on your FreeBSD system. -<itemize> -<item>Click the "DNS" tab -<item>In the "Host Name" field enter the name of the Windows NT box, in -this case: "Shemp". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "DNS Server Search Order" section, enter the IP address of -the DNS server that your ISP provided, clicking the "Add" button after -every address is entered. Repeat this step as many times as necessary -to add all of the addresses that your ISP provided. -</itemize> - -<p><bf>Other Windows NT TCP/IP options:</bf> - -<p>For our purposes the settings under the "WINS Address" and -"Routing" tabs are not used. - -<p>If you wish to use the Windows Internet Naming Service ("WINS") -your attention is invited to <url url="http://www.localnet.org"> for -more information about WINS settings, specifically regarding sharing -files transparently across the Internet. - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Properties section. - -<item>Click on the "Close" button to close the Network Control Panel. - -<item>Restart your computer if prompted to do so. -</itemize> - -<p>That's it! - -<sect1> -<heading>Configuring Windows for Workgroups</heading> - -<p>Configuring Windows for Workgroups to act as a network client -requires that the Microsoft TCP/IP-32 driver diskette has been -installed on the workstation. The TCP/IP drivers are not included -with the WfW CD or diskettes; if you need a copy they're available at -<url url="ftp://ftp.microsoft.com:/peropsys/windows/public/tcpip">. - -<p>Once the TCP/IP drivers have been loaded, perform the following -steps: - -<p><bf>Create the Windows for Workgroups "hosts" file:</bf> - -<p>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4. -<itemize> -<item>In Program Manager, click the "File" button; select "Run"; and -enter: "notepad \WINDOWS\HOSTS" (without the quotes) and click "OK" -<item>In the editor, enter the addresses and system names from the hosts -file shown in Section 3.4. -<item>When finished editing, close the notepad application (making sure -that you save the file!). -</itemize> - -<p><bf>Configure the Windows 95 TCP/IP Network Configuation -settings</bf> -<itemize> -<item>In the main window of Program Manager, open the "Network" group by -double-clicking the icon. -<item>Double click on the "Network Setup" icon. -<item>In the "Network Drivers Box" double-click the "Microsoft -TCP/IP-32" entry. -</itemize> - -<p><bf>Configure the Windows for Workgroups IP Address:</bf> <p>Ensure -the correct Ethernet Interface is selected in the "Adapter" list. If -not, scroll down until it is displayed and select it by clicking on -it. -<itemize> -<item>Ensure that the "Enable Automatic DHCP Configuration" check box is -blank. If it is checked, click it to remove the "X". -<item>In our example LAN the Windows for Workgroups system is the one -we've called "Moe"; in the "IP Address" field enter "192.168.1.3". -<item>Enter 255.255.255.0 in the "Subnet Mask" field. -</itemize> - -<p><bf>Configure the Gateway information:</bf> - -<p>For our example network the FreeBSD box will be acting as our -gateway to the Internet (routing packets between the Ethernet LAN and -the PPP dial-up connection). -<itemize> -<item>Enter the IP address of the FreeBSD system, 192.168.1.1, in the -"Default Gateway" field. -</itemize> - -<p><bf>Configuring DNS:</bf> - -<p>Again, this guide assumes that your Internet Service Provider has -given you a list of Domain Name Servers (or "DNS Servers") that you -should use. If you wish to run a DNS server on your local FreeBSD -system, refer to Section 6, "Exercise for the Interested Student" for -tips on setting up DNS on your FreeBSD system. -<itemize> -<item>Click the "DNS" button. -<item>In the "Host Name" field enter the name of the Windows for -Workgroups box, in this case: "Moe". -<item>In the "Domain" field enter the name of our local network, in this -case: "my.domain" -<item>In the "Domain Name Service (DNS) Search Order" section, enter the -IP address of the DNS server that your ISP provided, clicking the "Add" -button after each address is entered. Repeat this step as many times as -necessary to add all of the addresses that your ISP provided. -<item>Click on the "OK" button to close the DNS Configuration window. - -</itemize> - -<p><bf>Mopping up:</bf> -<itemize> -<item>Click on the "OK" button to close the TCP/IP Configuration window. - -<item>Click on the "OK" button to close the Network Setup window. -<item>Reboot your computer if prompted. -</itemize> - -<p>That's it! - -<sect> -<heading>Testing the Network</heading> - -<p> Once you've completed that appropriate tasks above you should have -a functioning PPP gateway to the Internet. - -<sect1> -<heading>Testing the Dial-Up link:</heading> - -<p> The first thing to test is that the connection is being made -between your modem and the ISP. - -<sect1> -<heading>Testing the Ethernet LAN</heading> - -<p> *** TBD *** -</sect> - -<sect> -<heading>Exercises for the Interested Student</heading> - -<p> -<sect1> -<heading>Creating a mini-DNS system</heading> - -<p>While managing a Domain Name Service (DNS) hierarchy can be a black -art, it is possible to set up a Mini-DNS server on the FreeBSD system -that also acts as your gateway to your ISP. - -<p>Building on the files in <tt>/etc/namedb</tt> when the FreeBSD -system was installed it's possible to create a name server that is -both authoritative for the example network shown here as well as a -front-door to the Internet DNS architecture. - -<p>In this minimal DNS configuration, only three files are necessary: -<tscreen><verb> -/etc/namedb/named.boot -/etc/namedb/named.root -/etc/namedb/mydomain.db -</verb></tscreen> - -<p>The <tt>/etc/namedb/named.root</tt> file is automatically installed -as part of the FreeBSD base installation; the other two files must be -created manually. - -<sect2> -<heading>The <tt>/etc/namedb/named.boot</tt> file</heading> -<p>The <tt>/etc/namedb/named.boot</tt> file controls the startup -settings of the DNS server. -Esentially, it tells the Name Server: -<enum> -<item>Where to find configuration files, -<item>What "domain names" it's responsible for, and -<item>Where to find other DNS servers. -</enum> - -<p>Using the '<tt/ee/' editor, create a -<tt>/etc/namedb/named.boot</tt> with the following contents: -<tscreen><verb> -; boot file for mini-name server - -directory /etc/namedb - -; type domain source host/file backup file - -cache . named.root -primary my.domain. mydomain.db -</verb></tscreen> -<p>Lines that begin with a semi-colon are comments. The significant -lines in this file are: -<itemize> -<item><tt>directory /etc/namedb</tt> -<p>Tells the Name Server where to find the configuration files -referenced in the remaining sections of the -'<tt>/etc/namedb/named.boot</tt>' file. -<item><tt>cache . named.root</tt> -<p>Tells the Name Server that the list of "Top-Level" DNS servers for -the Internet can be found in a file called '<tt>named.root</tt>'. -(This file is included in the base installation and its -contents are not described in this document.) -<item><tt>primary my.domain. mydomain.db</tt> -<p>Tells the Name Server that it will be "authoritative" for a DNS -domain called "my.domain" and that a list of names and IP addresses -for the systems in "my.domain" (the local network) -can be found in a file named '<tt>mydomain.db</tt>'. -</itemize> -<p>Once the <tt>/etc/namedb/named.boot</tt> file has been created and -saved, proceed to the next section to create the -<tt>/etc/namedb/mydomain.db</tt> file. - -<sect2> -<heading>The <tt>/etc/namedb/mydomain.db</tt> file</heading> - -<p>The <tt>/etc/namedb/mydomain.db</tt> file lists the names and IP -addresses of <em/every/ system in the Local Area Network. - -<p><em>For a detailed description of the statements used in this file, -refer to the <tt/named/ manpage.</em> - -<p>The <tt>/etc/namedb/mydomain.db</tt> file for our minimal DNS -server has the following contents: -<tscreen><verb> -@ IN SOA my.domain. root.my.domain. ( - 961230 ; Serial - 3600 ; Refresh - 300 ; Retry - 3600000 ; Expire - 3600 ) ; Minimum - IN NS curly.my.domain. - -curly.my.domain. IN A 192.168.1.1 # The FreeBSD box -larry.my.domain. IN A 192.168.1.2 # The Win'95 box -moe.my.domain. IN A 192.168.1.3 # The WfW box -shemp.my.domain. IN A 192.168.1.4 # The Windows NT box - -$ORIGIN 1.168.192.IN-ADDR.ARPA - IN NS curly.my.domain. -1 IN PTR curly.my.domain. -2 IN PTR larry.my.domain. -3 IN PTR moe.my.domain. -4 IN PTR shemp.my.domain. - -$ORIGIN 0.0.127.IN-ADDR.ARPA - IN NS curly.my.domain. -1 IN PTR localhost.my.domain. -</verb></tscreen> -<p>In simple terms, this file declares that the local DNS server is: -<itemize> -<item>The Start of Authority for ("SOA") for a domain called -'my.domain', -<item>The Name Server ("NS") for 'my.domain', -<item>Responsible for the reverse-mapping for all IP addresses that -start with '192.168.1.' and -'127.0.0.' ("$ORIGIN ...") -</itemize> - -<p>To add workstation entries to this file you'll need to add two -lines for each system; one in the top section where the name(s) are -mapped into Internet Addresses ("IN A"), and another line that maps -the addresses back into names in the <tt>$ORIGIN -1.168.192.IN-ADDR.ARPA</tt> section. - -<sect2> -<heading>Starting the DNS Server</heading> - -<p>By default the DNS server ('<tt>/usr/sbin/named</tt>') is not -started when the system boots. You can modify this behavior by -changing a single line in '<tt>/etc/rc.conf</tt>' as follows: - -<p> Using the '<tt/ee/' editor, load <tt>/etc/rc.conf</tt>. Scroll -down approximately 40 lines until you come to the section that says: -<tscreen><verb> ---- -named_enable="NO" # Run named, the DNS server (or NO). -named_flags="-b /etc/namedb/named.boot" # Flags to named (if enabled). ---- -</verb></tscreen> -Change this section to read: -<tscreen><verb> ---- -named_enable="YES" # Run named, the DNS server (or NO). -named_flags="-b /etc/namedb/named.boot" # Flags to named (if enabled). ---- -</verb></tscreen> -Save the file and reboot. - -Alternatively, start the Name Server daemon by entering the following -command: -<tscreen><verb> -# named -b /etc/namedb/named.boot -</verb></tscreen> - -<p>Whenever you modify any of the files in <tt>/etc/namedb</tt> you'll -need to kick-start the Name Server process to make it pick up the -modifications. This is performed with the following system command: -<tscreen><verb> -# kill -HUP `cat /var/run/named.pid` -</verb></tscreen> - -<sect1> -<heading>Playing with PPP filters</heading> - -<p>The PPP program has the ability to apply selected filtering rules -to the traffic it routes. While this is not nearly as secure as a -formal firewall it does provide some access control as to how the link -is used. - -<p>('<tt>man ipfw</tt>' for information on setting up a more secure -FreeBSD system.) - -<p>The complete documentation for the various filters and rules under -PPP are availabe in the PPP manpage. - -<p>There are four distinct classes of rules which may be applied to -the PPP program: -<itemize> -<item><tt/afilter/ - Access Counter (or "Keep Alive") filters -<p>These control which events are ignored by the <tt/set timeout=/ -statement in the configuration file. -<item><tt/dfilter/ - Dialing filters -<p>These filtering rules control which events are ignored by the -demand-dial mode of PPP. -<item><tt/ifilter/ - Input filters -<p>Control whether incoming packets should be discarded or passed into -the system. -<item><tt/ofilter/ - Output filters -<p>Control whether outgoing packets should be discarded or passed into -the system. -</itemize> -<p> - -What follows is a snippet from an operating system which provides a -good foundation for "normal" Internet operations while preventing PPP -from pumping <em/all/ data over the dial-up connection. Comments -briefly describe the logic of each rule set: -<tscreen><verb> -# -# KeepAlive filters -# Don't keep Alive with ICMP,DNS and RIP packet -# - set afilter 0 deny icmp - set afilter 1 deny udp src eq 53 - set afilter 2 deny udp dst eq 53 - set afilter 3 deny udp src eq 520 - set afilter 4 deny udp dst eq 520 - set afilter 5 permit 0/0 0/0 -# -# Dial Filters: -# Note: ICMP will trigger a dial-out in this configuration! -# - set dfilter 0 permit 0/0 0/0 -# -# Allow ident packet pass through -# - set ifilter 0 permit tcp dst eq 113 - set ofilter 0 permit tcp src eq 113 -# -# Allow telnet connection to the Internet -# - set ifilter 1 permit tcp src eq 23 estab - set ofilter 1 permit tcp dst eq 23 -# -# Allow ftp access to the Internet -# - set ifilter 2 permit tcp src eq 21 estab - set ofilter 2 permit tcp dst eq 21 - set ifilter 3 permit tcp src eq 20 dst gt 1023 - set ofilter 3 permit tcp dst eq 20 -# -# Allow access to DNS lookups -# - set ifilter 4 permit udp src eq 53 - set ofilter 4 permit udp dst eq 53 -# -# Allow DNS Zone Transfers -# - set ifilter 5 permit tcp src eq 53 - set ofilter 5 permit tcp dst eq 53 -# -# Allow access from/to local network -# - set ifilter 6 permit 0/0 192.168.1.0/24 - set ofilter 6 permit 192.168.1.0/24 0/0 -# -# Allow ping and traceroute response -# - set ifilter 7 permit icmp - set ofilter 7 permit icmp - set ifilter 8 permit udp dst gt 33433 - set ofilter 9 permit udp dst gt 33433 -# -# Allow cvsup -# - set ifilter 9 permit tcp src eq 5998 - set ofilter 9 permit tcp dst eq 5998 - set ifilter 10 permit tcp src eq 5999 - set ofilter 10 permit tcp dst eq 5999 -# -# Allow NTP for Time Synchronization -# - set ifilter 11 permit tcp src eq 123 dst eq 123 - set ofilter 11 permit tcp src eq 123 dst eq 123 - set ifilter 12 permit udp src eq 123 dst eq 123 - set ofilter 12 permit udp src eq 123 dst eq 123 -# -# SMTP'd be a good idea! -# - set ifilter 13 permit tcp src eq 25 - set ofilter 13 permit tcp dst eq 25 -# -# -# We use a lot of `whois`, let's pass that -# - set ifilter 14 permit tcp src eq 43 - set ofilter 14 permit tcp dst eq 43 - set ifilter 15 permit udp src eq 43 - set ofilter 15 permit udp dst eq 43 -# -# If none of above rules matches, then packet is blocked. -#------- -</verb></tscreen> -<p>Up to 20 distinct filtering rules can be applied to each class of -filter. Rules in each class are number sequentially from 0 to 20 -<em/but none of the rules for a particular filter class take affect -until ruleset '0' is defined!/ - -<p>If you choose <em/not/ to use Filtering Rules in the PPP -configuration then <em/ALL/ traffic will be permitted both into and -out of your system while it's connected to your ISP. - -If you decide that you want to implement filtering rules, add the -above lines to your <tt>/etc/ppp/ppp.conf</tt> file in either the -"default:", "demand:", or "interactive:" section (or all of them - the -choice is yours). - -</sect> - -</article> - |