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 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 @@ - - - - Advanced Networking - - - Gateways and Routes - - Contributed by &a.gryphon;. 6 October - 1995. - - 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 - destination, send along through this - gateway. 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. - - - An example - - To illustrate different aspects of routing, we will use the - following example which is the output of the command netstat - -r: - - 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 - - The first two lines specify the default route (which we will cover - in the next section) and the localhost route. - - The interface (Netif column) that it specifies - to use for localhost is - lo0, 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. - - The next thing that stands out are the 0:e0:... addresses. These are ethernet hardware - addresses. FreeBSD will automatically identify any hosts - (test0 in the example) on the local ethernet and add - a route for that host, directly to it over the ethernet interface, - ed0. There is also a timeout - (Expire 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. - - FreeBSD will also add subnet routes for the local subnet (10.20.30.255 is the broadcast address for the - subnet 10.20.30, and foobar.com is the domain name associated - with that subnet). The designation link#1 refers - to the first ethernet card in the machine. You will notice no - additional interface is specified for those. - - Both of these groups (local network hosts and local subnets) have - their routes automatically configured by a daemon called - routed. If this is not run, then only routes which - are statically defined (ie. entered explicitly) will exist. - - The host1 line refers to our host, which it - knows by ethernet address. Since we are the sending host, FreeBSD - knows to use the loopback interface (lo0) - rather than sending it out over the ethernet interface. - - The two host2 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 => symbol - after the lo0 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 link#1 line for - such. - - The final line (destination subnet 224) deals - with MultiCasting, which will be covered in a another section. - - The other column that we should talk about are the - Flags. Each route has different attributes that - are described in the column. Below is a short table of some of these - flags and their meanings: - - - - - - U - Up: The route is active. - - - - H - Host: The route destination is a single host. - - - - G - Gateway: Send anything for this destination on to this - remote system, which will figure out from there where to send - it. - - - - S - Static: This route was configured manually, not - automatically generated by the system. - - - - C - Clone: Generates a new route based upon this route for - machines we connect to. This type of route is normally used - for local networks. - - - - W - WasCloned: Indicated a route that was auto-configured - based upon a local area network (Clone) route. - - - - L - Link: Route involves references to ethernet - hardware. - - - - - - - - Default routes - - 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. - - 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 c 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). - - 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. - - Let us look at an example of default routes. This is a common - configuration: - - -[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW] - - - The hosts Local1 and Local2 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. - - The default routes for each of your machines will be: - - - - - - host - default gateway - interface - - - - - - Local2 - Local1 - ethernet - - - - Local1 - T1-GW - PPP - - - - - - 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?”. - - 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. - - As a final note, it is common to use the address ...1 as the gateway address for your local - network. So (using the same example), if your local class-C address - space was 10.20.30 and your ISP was - using 10.9.9 then the default routes - would be: - - -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) - - - - - Dual homed hosts - - 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. - - 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. - - 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. - - - - Routing propagation - - We have already talked about how we define our routes to the - outside world, but not about how the outside world finds us. - - 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. - - 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? - - 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. - - 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. - - - - Troubleshooting - - 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). - - 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. - - For more information, see the manual page for - &man.traceroute.8;. - - - - - NFS - - Contributed by &a.jlind;. - - 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. - - 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. - - 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 server, include the option - on the mount from the client. If the FreeBSD - system is the client, then mount the NFS file - system with the option . These options may be - specified using the fourth field of the fstab entry - on the client for automatic mounts, or by using the - parameter of the mount command for manual mounts. - - 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 certain that - your routers are routing the necessary UDP information, or you will not - get anywhere, no matter what else you are doing. - - In the following examples, fastws is the host - (interface) name of a high-performance workstation, and - freebox is the host (interface) name of a FreeBSD - system with a lower-performance Ethernet adapter. Also, - /sharedfs will be the exported NFS filesystem (see - man exports), and /project will - be the mount point on the client for the exported file system. In all - cases, note that additional options, such as or - and may be desirable in your - application. - - Examples for the FreeBSD system (freebox) as the - client: in /etc/fstab on freebox: - - -fastws:/sharedfs /project nfs rw,-r=1024 0 0 - - As a manual mount command on freebox: - - &prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /project - - Examples for the FreeBSD system as the server: in - /etc/fstab on fastws: - - -freebox:/sharedfs /project nfs rw,-w=1024 0 0 - - As a manual mount command on fastws: - - &prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /project - - Nearly any 16-bit Ethernet adapter will allow operation without the - above restrictions on the read or write size. - - 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 acknowledged 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. - - 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. - - 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. - - - - Diskless Operation - - Contributed by &a.martin;. - - netboot.com/netboot.rom - 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. - - Supported Ethernet cards include: Western Digital/SMC 8003, 8013, - 8216 and compatibles; NE1000/NE2000 and compatibles (requires - recompile) - - - Setup Instructions - - - - 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: - - - - HP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't - work) - - - - Sun/Solaris 2.3. (you may need to get bootp) - - - - - - Set up a bootp server to provide the client with IP, gateway, - netmask. - - -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: - - - - Set up a TFTP server (on same machine as bootp server) to - provide booting information to client. The name of this file is - cfg.X.X.X.X (or - /tftpboot/cfg.X.X.X.X, - it will try both) where X.X.X.X 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: - - - - - - help - print help list - - - - ip - - print/set client's IP address - - - - server - - print/set bootp/tftp server address - - - - netmask - - print/set netmask - - - - hostname name - print/set hostname - - - - kernel - - print/set kernel name - - - - rootfs - - print/set root filesystem - - - - swapfs - - print/set swap filesystem - - - - swapsize - - set diskless swapsize in Kbytes - - - - diskboot - boot from disk - - - - autoboot - continue boot process - - - - trans - | - turn transceiver on|off - - - - flags - - set boot flags - - - - - - A typical completely diskless cfg file might contain: - - -rootfs 192.1.2.3:/rootfs/myclient -swapfs 192.1.2.3:/swapfs -swapsize 20000 -hostname myclient.mydomain - - A cfg file for a machine with local swap might contain: - - -rootfs 192.1.2.3:/rootfs/myclient -hostname myclient.mydomain - - - - 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 - /etc/exports file on FreeBSD might look - like: - - -/rootfs/myclient -maproot=0:0 myclient.mydomain -/swapfs -maproot=0:0 myclient.mydomain - - And on HP-UX: - - -/rootfs/myclient -root=myclient.mydomain -/swapfs -root=myclient.mydomain - - - - If you are swapping over NFS (completely diskless - configuration) create a swap file for your client using - dd. If your swapfs command - has the arguments /swapfs and the size 20000 - as in the example above, the swapfile for myclient will be called - /swapfs/swap.X.X.X.X - where X.X.X.X is the client's IP addr, - eg: - - &prompt.root; dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000 - - 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: - - &prompt.root; chmod 0600 /swapfs/swap.192.1.2.4 - - - - Unpack the root filesystem in the directory the client will - use for its root filesystem (/rootfs/myclient - in the example above). - - - - 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. - - - - When extracting /dev in - /rootfs/myclient, 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 - /dev and do a sh ./MAKEDEV - all from the client to fix this. - - - - - - Run netboot.com on the client or make an - EPROM from the netboot.rom file - - - - - - Using Shared <filename>/</filename> and <filename>/usr</filename> - filesystems - - At present there isn't an officially sanctioned way of doing this, - although I have been using a shared /usr - filesystem and individual / filesystems for each - client. If anyone has any suggestions on how to do this cleanly, - please let me and/or the &a.core; know. - - - - Compiling netboot for specific setups - - Netboot can be compiled to support NE1000/2000 cards by changing - the configuration in - /sys/i386/boot/netboot/Makefile. See the - comments at the top of this file. - - - - - ISDN - - Last modified by &a.wlloyd;. - - A good resource for information on ISDN technology and hardware is - Dan Kegel's ISDN - Page. - - A quick simple roadmap to ISDN follows: - - - - If you live in Europe I suggest you investigate the ISDN card - section. - - - - 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. - - - - 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. - - - - Cost is a significant factor in determining what solution you will - choose. The following options are listed from least expensive to most - expensive. - - - ISDN Cards - - Contributed by &a.hm;. - - This section is really only relevant to ISDN users in countries - where the DSS1/Q.931 ISDN standard is supported. - - 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. - - The latest isdn4bsd version is available from ftp://isdn4bsd@ftp.consol.de/pub/, - the main isdn4bsd ftp site (you have to log in as user - isdn4bsd , give your mail address as the password - and change to the pub directory. Anonymous ftp - as user ftp or anonymous - will not give the desired result). - - 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. - - 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 README - file. - - 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 hm@kts.org. - - A majordomo maintained mailing list is available. To join the - list, send mail to majordomo@FreeBSD.org and - specify: - - -subscribe freebsd-isdn - - in the body of your message. - - - - ISDN Terminal Adapters - - Terminal adapters(TA), are to ISDN what modems are to regular - phone lines. - - Most TA's use the standard hayes modem AT command set, and can be - used as a drop in replacement for a modem. - - 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 PPP exactly the same - as for a modem setup. Make sure you set your serial speed as high as - possible. - - 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. - - 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. - - If you want maximum stability, use the kernel PPP option, not the user-land iijPPP. - - The following TA's are know to work with FreeBSD. - - - - Motorola BitSurfer and Bitsurfer Pro - - - - Adtran - - - - 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. - - The real problem with external TA's is like modems you need a good - serial card in your computer. - - You should read the serial ports - section in the handbook for a detailed understanding of serial - devices, and the differences between asynchronous and synchronous - serial ports. - - 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. - - 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. - - 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. - - 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 archives for the - complete discussion. - - - - Standalone ISDN Bridges/Routers - - 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. - - In the context of this page, I will use router and bridge - interchangeably. - - 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. - - A router will allow you much faster throughput that a standard TA, - since it will be using a full synchronous ISDN connection. - - 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. - - 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. - - For example to connect a home computer or branch office network to - a head office network the following setup could be used. - - - Branch office or Home network - - Network is 10 Base T Ethernet. Connect router to network cable - with AUI/10BT transceiver, if necessary. - - - ----Sun workstation -| ----FreeBSD box -| ----Windows 95 (Do not admit to owning it) -| -Standalone router - | -ISDN BRI line - - If your home/branch office is only one computer you can use a - twisted pair crossover cable to connect to the standalone router - directly. - - - - Head office or other lan - - Network is Twisted Pair Ethernet. - - - - -------Novell Server - | H | - | ---Sun - | | - | U ---FreeBSD - | | - | ---Windows 95 - | B | - |___---Standalone router - | - ISDN BRI line - - - One large advantage of most routers/bridges is that they allow you - to have 2 separate independent PPP connections to - 2 separate sites at the same 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. - - 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. - - 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. - - - - - - 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 @@ - - -abial@FreeBSD.org"> - -ache@FreeBSD.org"> - -adam@FreeBSD.org"> - -alc@FreeBSD.org"> - -alex@FreeBSD.org"> - -alfred@FreeBSD.org"> - -amurai@FreeBSD.org"> - -andreas@FreeBSD.org"> - -archie@FreeBSD.org"> - -asami@FreeBSD.org"> - -ats@FreeBSD.org"> - -awebster@pubnix.net"> - -bde@FreeBSD.org"> - -billf@FreeBSD.org"> - -brandon@FreeBSD.org"> - -brian@FreeBSD.org"> - -cawimm@FreeBSD.org"> - -cg@FreeBSD.org"> - -charnier@FreeBSD.org"> - -chris@FreeBSD.org"> - -chuckr@glue.umd.edu"> - -chuckr@FreeBSD.org"> - -cpiazza@FreeBSD.org"> - -cracauer@FreeBSD.org"> - -csgr@FreeBSD.org"> - -cwt@FreeBSD.org"> - -danny@FreeBSD.org"> - -darrenr@FreeBSD.org"> - -davidn@blaze.net.au"> - -dbaker@FreeBSD.org"> - -dburr@FreeBSD.org"> - -dcs@FreeBSD.org"> - -deischen@FreeBSD.org"> - -des@FreeBSD.org"> - -dfr@FreeBSD.org"> - -dg@FreeBSD.org"> - -dick@FreeBSD.org"> - -dillon@FreeBSD.org"> - -dima@FreeBSD.org"> - -dirk@FreeBSD.org"> - -Dirk.vanGulik@jrc.it"> - -dt@FreeBSD.org"> - -dufault@FreeBSD.org"> - -dwhite@FreeBSD.org"> - -dyson@FreeBSD.org"> - -eivind@FreeBSD.org"> - -ejc@FreeBSD.org"> - -erich@FreeBSD.org"> - -faq@FreeBSD.org"> - -fenner@FreeBSD.org"> - -flathill@FreeBSD.org"> - -foxfair@FreeBSD.org"> - -fsmp@FreeBSD.org"> - -gallatin@FreeBSD.org"> - -gclarkii@FreeBSD.org"> - -gehenna@FreeBSD.org"> - -gena@NetVision.net.il"> - -ghelmer@cs.iastate.edu"> - -gibbs@FreeBSD.org"> - -gj@FreeBSD.org"> - -gpalmer@FreeBSD.org"> - -graichen@FreeBSD.org"> - -green@FreeBSD.org"> - -grog@FreeBSD.org"> - -gryphon@healer.com"> - -guido@FreeBSD.org"> - -hanai@FreeBSD.org"> - -handy@sxt4.physics.montana.edu"> - -helbig@FreeBSD.org"> - -hm@FreeBSD.org"> - -hoek@FreeBSD.org"> - -hosokawa@FreeBSD.org"> - -hsu@FreeBSD.org"> - -imp@FreeBSD.org"> - -itojun@itojun.org"> - -iwasaki@FreeBSD.org"> - -jasone@FreeBSD.org"> - -jb@cimlogic.com.au"> - -jdp@FreeBSD.org"> - -jehamby@lightside.com"> - -jfieber@FreeBSD.org"> - -jfitz@FreeBSD.org"> - -jgreco@FreeBSD.org"> - -jhay@FreeBSD.org"> - -jhs@FreeBSD.org"> - -jim@FreeBSD.org"> - -jkh@FreeBSD.org"> - -jkoshy@FreeBSD.org"> - -jlemon@FreeBSD.org"> - -john@starfire.MN.ORG"> - -jlrobin@FreeBSD.org"> - -jmacd@FreeBSD.org"> - -jmb@FreeBSD.org"> - -jmg@FreeBSD.org"> - -jmz@FreeBSD.org"> - -joerg@FreeBSD.org"> - -john@FreeBSD.org"> - -jraynard@FreeBSD.org"> - -jseger@FreeBSD.org"> - -julian@FreeBSD.org"> - -jvh@FreeBSD.org"> - -karl@FreeBSD.org"> - -kato@FreeBSD.org"> - -kelly@plutotech.com"> - -ken@FreeBSD.org"> - -kevlo@FreeBSD.org"> - -kjc@FreeBSD.org"> - -kris@FreeBSD.org"> - -kuriyama@FreeBSD.org"> - -lars@FreeBSD.org"> - -lile@FreeBSD.org"> - -ljo@FreeBSD.org"> - -luoqi@FreeBSD.org"> - -marcel@FreeBSD.org"> - -markm@FreeBSD.org"> - -martin@FreeBSD.org"> - -max@FreeBSD.org"> - -mark@vmunix.com"> - -mbarkah@FreeBSD.org"> - -mckay@FreeBSD.org"> - -mckusick@FreeBSD.org"> - -md@bsc.no"> - -winter@jurai.net"> - -mharo@FreeBSD.org"> - -mjacob@FreeBSD.org"> - -mks@FreeBSD.org"> - -motoyuki@FreeBSD.org"> - -mph@FreeBSD.org"> - -mpp@FreeBSD.org"> - -msmith@FreeBSD.org"> - -nate@FreeBSD.org"> - -nectar@FreeBSD.org"> - -newton@FreeBSD.org"> - -n_hibma@FreeBSD.org"> - -nik@FreeBSD.org"> - -nsayer@FreeBSD.org"> - -nsj@FreeBSD.org"> - -nyan@FreeBSD.org"> - -obrien@FreeBSD.org"> - -olah@FreeBSD.org"> - -opsys@open-systems.net"> - -paul@FreeBSD.org"> - -pb@fasterix.freenix.org"> - -pds@FreeBSD.org"> - -peter@FreeBSD.org"> - -phk@FreeBSD.org"> - -pjchilds@imforei.apana.org.au"> - -proven@FreeBSD.org"> - -pst@FreeBSD.org"> - -rgrimes@FreeBSD.org"> - -rhuff@cybercom.net"> - -ricardag@ag.com.br"> - -rich@FreeBSD.org"> - -rnordier@FreeBSD.org"> - -roberto@FreeBSD.org"> - -rse@FreeBSD.org"> - -ru@FreeBSD.org"> - -sada@FreeBSD.org"> - -scrappy@FreeBSD.org"> - -se@FreeBSD.org"> - -sef@FreeBSD.org"> - -sheldonh@FreeBSD.org"> - -shige@FreeBSD.org"> - -shin@FreeBSD.org"> - -simokawa@FreeBSD.org"> - -smace@FreeBSD.org"> - -smpatel@FreeBSD.org"> - -sos@FreeBSD.org"> - -stark@FreeBSD.org"> - -stb@FreeBSD.org"> - -steve@FreeBSD.org"> - -sumikawa@FreeBSD.org"> - -swallace@FreeBSD.org"> - -tanimura@FreeBSD.org"> - -taoka@FreeBSD.org"> - -tedm@FreeBSD.org"> - -tegge@FreeBSD.org"> - -tg@FreeBSD.org"> - -thepish@FreeBSD.org"> - -tom@FreeBSD.org"> - -torstenb@FreeBSD.org"> - -truckman@FreeBSD.org"> - -ugen@FreeBSD.org"> - -uhclem@FreeBSD.org"> - -ulf@FreeBSD.org"> - -vanilla@FreeBSD.org"> - -wes@FreeBSD.org"> - -whiteside@acm.org"> - -wilko@yedi.iaf.nl"> - -wlloyd@mpd.ca"> - -wollman@FreeBSD.org"> - -wosch@FreeBSD.org"> - -wpaul@FreeBSD.org"> - -yokota@FreeBSD.org"> 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 @@ - - - - Backups - - 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 the kernel - configuration file section in this handbook for a list of - supported devices. - - 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 Mailing Lists 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. - - - * What about backups to floppies? - - - - - - Tape Media - - The major tape media are the 4mm, 8mm, QIC, mini-cartridge and - DLT. - - - 4mm (DDS: Digital Data Storage) - - 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. - - 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. - - 4mm drives, like 8mm drives, use helical-scan. All the benefits - and drawbacks of helical-scan apply to both 4mm and 8mm drives. - - Tapes should be retired from use after 2,000 passes or 100 full - backups. - - - - 8mm (Exabyte) - - 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. - - 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. - - 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. - - - - QIC - - 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 - most 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). Mini-cartridges, which - also use 1/4" wide tape are discussed separately. Tape libraries and - changers are not available. - - 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. - - 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). - - Tapes should be retired from use after 5,000 backups. - - - - * Mini-Cartridge - - - - - - DLT - - 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. - - 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. - - 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. - - - - Using a new tape for the first time - - 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: - - sa0(ncr1:4:0): NOT READY asc:4,1 -sa0(ncr1:4:0): Logical unit is in process of becoming ready - - 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: - - mt fsf 1 causes the tape drive to write an - Identifier Block to the tape. - - Use the front panel button to eject the tape. - - Re-insert the tape and &man.dump.8; data to the tape. - - &man.dump.8; will report DUMP: End of tape - detected and the console will show: HARDWARE - FAILURE info:280 asc:80,96 - - rewind the tape using: mt rewind - - Subsequent tape operations are successful. - - - - - Backup Programs - - The three major programs are - &man.dump.8;, - &man.tar.1;, - and - &man.cpio.1;. - - - Dump and Restore - - &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. - - &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 - rhosts 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 rdump'ing from - a FreeBSD computer to an Exabyte tape drive connected to a Sun called - komodo, use: /sbin/rdump 0dsbfu 54000 13000 - 126 komodo:/dev/nrsa8 /dev/rda0a 2>&1) Beware: there - are security implications to allowing rhosts - commands. Evaluate your situation carefully. - - - - Tar - - &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. - - 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 - komodo, use: /usr/bin/tar cf - komodo:/dev/nrsa8 . 2>&1. 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) - - - - Cpio - - &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 stdin. - - &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) - - - - Pax - - &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;. - - - - Amanda - - Amanda - (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. - - 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. - - - - Do nothing - - “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! - - 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. - - “Do nothing” is the correct backup method for - /usr/obj 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 - SGML input files. Creating backups of these - HTML files is not necessary. The - SGML source files are backed up regularly. - - - - Which Backup Program is Best? - - &man.dump.8; Period. 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 torture-testing - Backup and Archive Programs. - - - - Emergency Restore Procedure - - - Before the Disaster - - There are only four steps that you need to perform in - preparation for any disaster that may occur. - - First, print the disklabel from each of your disks - (e.g. disklabel da0 | lpr), your filesystem table - (/etc/fstab) and all boot messages, two copies of - each. - - Second, determine that the boot and fixit floppies - (boot.flp and fixit.flp) - 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. - - 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;. - - Third, create backup tapes regularly. Any changes that you make - after your last backup may be irretrievably lost. Write-protect the - backup tapes. - - Fourth, test the floppies (either boot.flp - and fixit.flp 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 tar xvf /dev/rsa0, you - might accidently type tar cvf /dev/rsa0 and - over-write your backup tape). - - 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. - - An example script for creating a bootable floppy: - - - /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 < /mnt/etc/passwd < /mnt/etc/master.passwd < - - - - After the Disaster - - The key question is: did your hardware survive? You have been - doing regular backups so there is no need to worry about the - software. - - If the hardware has been damaged. First, replace those parts - that have been damaged. - - If your hardware is okay, check your floppies. If you are using - a custom boot floppy, boot single-user (type -s - at the boot: prompt). Skip the following - paragraph. - - If you are using the boot.flp and - fixit.flp floppies, keep reading. Insert the - boot.flp floppy in the first floppy drive and - boot the computer. The original install menu will be displayed on - the screen. Select the Fixit--Repair mode with CDROM or - floppy. option. Insert the - fixit.flp when prompted. - restore and the other programs that you need are - located in /mnt2/stand. - - Recover each filesystem separately. - - Try to &man.mount.8; (e.g. mount /dev/da0a - /mnt) 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 (mount -u -o rw - /mnt). Use your backup program and backup tapes to - recover the data for this filesystem (e.g. restore vrf - /dev/sa0). Unmount the filesystem (e.g. umount - /mnt) Repeat for each filesystem that was - damaged. - - 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. - - - - * I did not prepare for the Disaster, What Now? - - - - - - - - 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 @@ - - - - Unix Basics - - - The Online Manual - - The most comprehensive documentation on FreeBSD is in the form of - man pages. 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 - man command. Use of the man - command is simple: - - &prompt.user; man command - - command is the name of the command you - wish to learn about. For example, to learn more about - ls command type: - - &prompt.user; man ls - - The online manual is divided up into numbered sections: - - - - User commands - - - - System calls and error numbers - - - - Functions in the C libraries - - - - Device drivers - - - - File formats - - - - Games and other diversions - - - - Miscellaneous information - - - - System maintenance and operation commands - - - - Kernel developers - - - - In some cases, the same topic may appear in more than one section of - the on-line manual. For example, there is a chmod - user command and a chmod() system call. In this - case, you can tell the man command which one you want - by specifying the section: - - &prompt.user; man 1 chmod - - This will display the manual page for the user command - chmod. 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 - chmod user command and &man.chmod.2; refers to the - system call. - - 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 man to search for keywords in the command - descriptions by using the - switch: - - &prompt.user; man -k mail - - 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 apropos - command. - - So, you are looking at all those fancy commands in - /usr/bin but do not even have the faintest idea - what most of them actually do? Simply do a - - &prompt.user; cd /usr/bin; man -f * - - or - - &prompt.user; cd /usr/bin; whatis * - - which does the same thing. - - - - GNU Info Files - - 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 - info command or, if you installed - emacs, the info mode of - emacs. - - To use the &man.info.1; command, simply type: - - &prompt.user; info - - For a brief introduction, type h. For a - quick command reference, type ?. - - - - - 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 @@ - - - - Bibliography - - 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. - - - Books & Magazines Specific to FreeBSD - - International books & - Magazines: - - - - Using - FreeBSD (in Chinese). - - - - FreeBSD for PC 98'ers (in Japanese), published by SHUWA System - Co, LTD. ISBN 4-87966-468-5 C3055 P2900E. - - - - FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2 - C3055 P2400E. - - - - Complete Introduction to FreeBSD (in Japanese), published by Shoeisha Co., Ltd. ISBN 4-88135-473-6 P3600E. - - - - Personal UNIX Starter Kit FreeBSD (in Japanese), published by ASCII. ISBN 4-7561-1733-3 P3000E. - - - - FreeBSD Handbook (Japanese translation), published by ASCII. ISBN 4-7561-1580-2 - P3800E. - - - - FreeBSD mit Methode (in German), published by Computer und - Literatur Verlag/Vertrieb Hanser, 1998. ISBN 3-932311-31-0. - - - - FreeBSD Install and Utilization Manual (in Japanese), published by Mainichi Communications Inc.. - - - - English language books & Magazines: - - - - The - Complete FreeBSD, published by Walnut Creek CDROM. - - - - - - Users' Guides - - - - Computer Systems Research Group, UC Berkeley. 4.4BSD - User's Reference Manual. O'Reilly & Associates, - Inc., 1994. ISBN 1-56592-075-9 - - - - Computer Systems Research Group, UC Berkeley. 4.4BSD - User's Supplementary Documents. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-076-7 - - - - UNIX in a Nutshell. O'Reilly & - Associates, Inc., 1990. ISBN 093717520X - - - - Mui, Linda. What You Need To Know When You Can't Find - Your UNIX System Administrator. O'Reilly & - Associates, Inc., 1995. ISBN 1-56592-104-6 - - - - Ohio State - University has written a UNIX - Introductory Course which is available online in HTML and - postscript format. - - - - Jpman Project, Japan - FreeBSD Users Group. FreeBSD User's - Reference Manual (Japanese translation). Mainichi Communications - Inc., 1998. ISBN4-8399-0088-4 P3800E. - - - - - - Administrators' Guides - - - - Albitz, Paul and Liu, Cricket. DNS and - BIND, 2nd Ed. O'Reilly & Associates, Inc., 1997. - ISBN 1-56592-236-0 - - - - Computer Systems Research Group, UC Berkeley. 4.4BSD - System Manager's Manual. O'Reilly & Associates, - Inc., 1994. ISBN 1-56592-080-5 - - - - Costales, Brian, et al. Sendmail, 2nd Ed. - O'Reilly & Associates, Inc., 1997. ISBN 1-56592-222-0 - - - - Frisch, Æleen. Essential System - Administration, 2nd Ed. O'Reilly & Associates, - Inc., 1995. ISBN 1-56592-127-5 - - - - Hunt, Craig. TCP/IP Network - Administration. O'Reilly & Associates, Inc., 1992. - ISBN 0-937175-82-X - - - - Nemeth, Evi. UNIX System Administration - Handbook. 2nd Ed. Prentice Hall, 1995. ISBN - 0131510517 - - - - Stern, Hal Managing NFS and NIS O'Reilly - & Associates, Inc., 1991. ISBN 0-937175-75-7 - - - - Jpman Project, Japan - FreeBSD Users Group. FreeBSD System - Administrator's Manual (Japanese translation). Mainichi Communications - Inc., 1998. ISBN4-8399-0109-0 P3300E. - - - - - - Programmers' Guides - - - - Asente, Paul. X Window System Toolkit. - Digital Press. ISBN 1-55558-051-3 - - - - Computer Systems Research Group, UC Berkeley. 4.4BSD - Programmer's Reference Manual. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-078-3 - - - - Computer Systems Research Group, UC Berkeley. 4.4BSD - Programmer's Supplementary Documents. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-079-1 - - - - Harbison, Samuel P. and Steele, Guy L. Jr. C: A - Reference Manual. 4rd ed. Prentice Hall, 1995. - ISBN 0-13-326224-3 - - - - Kernighan, Brian and Dennis M. Ritchie. The C - Programming Language.. PTR Prentice Hall, 1988. - ISBN 0-13-110362-9 - - - - Lehey, Greg. Porting UNIX Software. - O'Reilly & Associates, Inc., 1995. ISBN 1-56592-126-7 - - - - Plauger, P. J. The Standard C Library. - Prentice Hall, 1992. ISBN 0-13-131509-9 - - - - Stevens, W. Richard. Advanced Programming in the UNIX - Environment. Reading, Mass. : Addison-Wesley, 1992 - ISBN 0-201-56317-7 - - - - Stevens, W. Richard. UNIX Network - Programming. 2nd Ed, PTR Prentice Hall, 1998. ISBN - 0-13-490012-X - - - - Wells, Bill. “Writing Serial Drivers for UNIX”. - Dr. Dobb's Journal. 19(15), December 1994. - pp68-71, 97-99. - - - - - - Operating System Internals - - - - Andleigh, Prabhat K. UNIX System - Architecture. Prentice-Hall, Inc., 1990. ISBN - 0-13-949843-5 - - - - Jolitz, William. “Porting UNIX to the 386”. - Dr. Dobb's Journal. January 1991-July - 1992. - - - - Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and - John Quarterman The Design and Implementation of the - 4.3BSD UNIX Operating System. Reading, Mass. : - Addison-Wesley, 1989. ISBN 0-201-06196-1 - - - - Leffler, Samuel J., Marshall Kirk McKusick, The Design - and Implementation of the 4.3BSD UNIX Operating System: Answer - Book. Reading, Mass. : Addison-Wesley, 1991. ISBN - 0-201-54629-9 - - - - McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and - John Quarterman. The Design and Implementation of the - 4.4BSD Operating System. Reading, Mass. : - Addison-Wesley, 1996. ISBN 0-201-54979-4 - - - - Stevens, W. Richard. TCP/IP Illustrated, Volume 1: - The Protocols. Reading, Mass. : Addison-Wesley, - 1996. ISBN 0-201-63346-9 - - - - Schimmel, Curt. Unix Systems for Modern - Architectures. Reading, Mass. : Addison-Wesley, 1994. - ISBN 0-201-63338-8 - - - - Stevens, W. Richard. TCP/IP Illustrated, Volume 3: - TCP for Transactions, HTTP, NNTP and the UNIX Domain - Protocols. Reading, Mass. : Addison-Wesley, 1996. - ISBN 0-201-63495-3 - - - - Vahalia, Uresh. UNIX Internals -- The New - Frontiers. Prentice Hall, 1996. ISBN - 0-13-101908-2 - - - - Wright, Gary R. and W. Richard Stevens. TCP/IP - Illustrated, Volume 2: The Implementation. Reading, - Mass. : Addison-Wesley, 1995. ISBN 0-201-63354-X - - - - - - Security Reference - - - - Cheswick, William R. and Steven M. Bellovin. Firewalls - and Internet Security: Repelling the Wily Hacker. - Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-63357-4 - - - - Garfinkel, Simson and Gene Spafford. Practical UNIX - Security. 2nd Ed. O'Reilly & Associates, Inc., - 1996. ISBN 1-56592-148-8 - - - - Garfinkel, Simson. PGP Pretty Good - Privacy O'Reilly & Associates, Inc., 1995. ISBN - 1-56592-098-8 - - - - - - Hardware Reference - - - - Anderson, Don and Tom Shanley. Pentium Processor - System Architecture. 2nd Ed. Reading, Mass. : - Addison-Wesley, 1995. ISBN 0-201-40992-5 - - - - Ferraro, Richard F. Programmer's Guide to the EGA, - VGA, and Super VGA Cards. 3rd ed. Reading, Mass. : - Addison-Wesley, 1995. ISBN 0-201-62490-7 - - - - Intel Corporation publishes documentation on their CPUs, - chipsets and standards on their developer web site, - usually as PDF files. - - - - Shanley, Tom. 80486 System Architecture. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40994-1 - - - - Shanley, Tom. ISA System Architecture. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40996-8 - - - - Shanley, Tom. PCI System Architecture. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40993-3 - - - - Van Gilluwe, Frank. The Undocumented PC. - Reading, Mass: Addison-Wesley Pub. Co., 1994. ISBN - 0-201-62277-7 - - - - - - UNIX History - - - - Lion, John Lion's Commentary on UNIX, 6th Ed. With - Source Code. ITP Media Group, 1996. ISBN - 1573980137 - - - - Raymond, Eric S. The New Hacker's Dictionary, 3rd - edition. MIT Press, 1996. ISBN - 0-262-68092-0. Also known as the Jargon - File - - - - Salus, Peter H. A quarter century of UNIX. - Addison-Wesley Publishing Company, Inc., 1994. ISBN - 0-201-54777-5 - - - - Simon Garfinkel, Daniel Weise, Steven Strassmann. The - UNIX-HATERS Handbook. IDG Books Worldwide, Inc., - 1994. ISBN 1-56884-203-1 - - - - Don Libes, Sandy Ressler Life with UNIX - — special edition. Prentice-Hall, Inc., 1989. ISBN - 0-13-536657-7 - - - - The BSD family tree. 1997. ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree or local on a FreeBSD-current machine. - - - - The BSD Release Announcements collection. - 1997. http://www.de.FreeBSD.org/de/ftp/releases/ - - - - Networked Computer Science Technical Reports - Library. http://www.ncstrl.org/ - - - - Old BSD releases from the Computer Systems Research - group (CSRG). http://www.mckusick.com/csrg/: - 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. - - - - - - Magazines and Journals - - - - The C/C++ Users Journal. R&D - Publications Inc. ISSN 1075-2838 - - - - Sys Admin — The Journal for UNIX System - Administrators Miller Freeman, Inc., ISSN - 1061-2688 - - - - - - - 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 @@ - 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 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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 @@ - - - - Contributing to FreeBSD - - Contributed by &a.jkh;. - - 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 - relies 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! - - 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. - - 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 TODO 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! - - 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. - - - What Is Needed - - The following list of tasks and sub-projects represents something of - an amalgam of the various core team TODO 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? - - - High priority tasks - - The following tasks are considered to be urgent, usually because - they represent something that is badly broken or sorely needed: - - - - 3-stage boot issues. Overall coordination: &a.hackers; - - - - Do WinNT compatible drive tagging so that the 3rd stage - can provide an accurate mapping of BIOS geometries for - disks. - - - - - - Filesystem problems. Overall coordination: &a.fs; - - - - Fix the MSDOS file system. - - - - Clean up and document the nullfs filesystem code. - Coordinator: &a.eivind; - - - - Fix the union file system. Coordinator: &a.dg; - - - - - - Implement Int13 vm86 disk driver. Coordinator: - &a.hackers; - - - - New bus architecture. Coordinator: &a.newbus; - - - - Port existing ISA drivers to new architecture. - - - - Move all interrupt-management code to appropriate parts of - the bus drivers. - - - - Port PCI subsystem to new architecture. Coordinator: - &a.dfr; - - - - 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. - - - - Resolve the probe/attach priority issue once and for - all. - - - - Move any remaining buses over to the new - architecture. - - - - - - Kernel issues. Overall coordination: &a.hackers; - - - - Add more pro-active security infrastructure. Overall - coordination: &a.security; - - - - 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; - - - - Make the entire kernel use suser() - instead of comparing to 0. It is presently using about half - of each. Coordinator: &a.eivind; - - - - 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; - - - - 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. - - - - 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; - - - - Add authorization infrastructure to the kernel, to allow - different authorization policies. Part of this could be done - by modifying suser(). Coordinator: - &a.eivind; - - - - Add code to the NFS layer so that you cannot - chdir("..") out of an NFS partition. E.g., - /usr is a UFS partition with - /usr/src NFS exported. Now it is - possible to use the NFS filehandle for - /usr/src to get access to - /usr. - - - - - - - - Medium priority tasks - - The following tasks need to be done, but not with any particular - urgency: - - - - Full KLD based driver support/Configuration Manager. - - - - 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. - - - - - - PCMCIA/PCCARD. Coordinators: &a.msmith; and &a.phk; - - - - Documentation! - - - - Reliable operation of the pcic driver (needs - testing). - - - - Recognizer and handler for sio.c - (mostly done). - - - - Recognizer and handler for ed.c - (mostly done). - - - - Recognizer and handler for ep.c - (mostly done). - - - - User-mode recognizer and handler (partially done). - - - - - - Advanced Power Management. Coordinators: &a.msmith; and - &a.phk; - - - - APM sub-driver (mostly done). - - - - IDE/ATA disk sub-driver (partially done). - - - - syscons/pcvt sub-driver. - - - - Integration with the PCMCIA/PCCARD drivers - (suspend/resume). - - - - - - - - Low priority tasks - - 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: - - The first N items are from Terry Lambert - terry@lambert.org - - - - 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. - - - - An "upgrade system" option that works on Linux boxes instead - of just previous rev FreeBSD boxes. - - - - Symmetric Multiprocessing with kernel preemption (requires - kernel preemption). - - - - 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). - - - - - - Smaller tasks - - 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. - - - - If you run FreeBSD-current and have a good Internet - connection, there is a machine current.FreeBSD.org 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. - - - - 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. - - - - 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). - - - - 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. - - - - 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. - - - - 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. - - - - Move contributed software to src/contrib - in the source tree. - - - - Make sure code in src/contrib is up to - date. - - - - Look for year 2000 bugs (and fix any you find!) - - - - Build the source tree (or just part of it) with extra warnings - enabled and clean up the warnings. - - - - Fix warnings for ports which do deprecated things like using - gets() or including malloc.h. - - - - 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) - - - - Suggest further tasks for this list! - - - - - - Work through the PR database - - The FreeBSD PR - list 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. - - 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. - - - - - How to Contribute - - Contributions to the system generally fall into one or more of the - following 6 categories: - - - Bug reports and general commentary - - An idea or suggestion of general technical - interest should be mailed to the &a.hackers;. Likewise, people with - an interest in such things (and a tolerance for a - high volume of mail!) may subscribe to the - hackers mailing list by sending mail to &a.majordomo;. See mailing lists for more information - about this and other mailing lists. - - If you find a bug or are submitting a specific change, please - report it using the &man.send-pr.1; program or its WEB-based - equivalent. Try to fill-in each field of the bug report. - Unless they exceed 65KB, include any patches directly in the report. - When including patches, do not 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 ftp.FreeBSD.org:/pub/FreeBSD/incoming/. - - 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 - bug-followup@FreeBSD.org. Use the number as the - message subject, e.g. "Re: kern/3377". Additional - information for any bug report should be submitted this way. - - 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;. - - - - Changes to the documentation - - Changes to the documentation are overseen by the &a.doc;. Send - submissions and changes (even small ones are welcome!) using - send-pr as described in Bug Reports and General - Commentary. - - - - Changes to existing source code - - 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 Staying current with FreeBSD for more - information about getting and using FreeBSD-current. - - 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. - - 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: - - - &prompt.user; diff -c oldfile newfile - - or - - &prompt.user; diff -c -r olddir newdir - - 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. - - 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 Bug Reports and General Commentary. - Do not 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. - - If you feel it appropriate (e.g. you have added, deleted, or - renamed files), bundle your changes into a tar file - and run the &man.uuencode.1; program on it. Shar archives are also - welcome. - - 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 very busy and so you - should only send mail to them where it is truly necessary. - - Please refer to man 9 intro and man 9 - style for some information on coding style. We would - appreciate it if you were at least aware of this information before - submitting code. - - - - New code or major value-added packages - - 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 ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming. - - When working with large amounts of code, the touchy subject of - copyrights also invariably comes up. Acceptable copyrights for code - included in FreeBSD are: - - - - 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. - - - - 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 - /sys/gnu or - /usr/src/gnu, and is therefore easily - identifiable to anyone for whom the GPL presents a problem. - - - - 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. - - 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 %% - with the appropriate information. - - -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$ - - For your convenience, a copy of this text can be found in - /usr/share/examples/etc/bsd-style-copyright. - - - - Money, Hardware or Internet access - - 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. - - - <anchor id="donations">Donating funds - - 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. - - 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. - - Please make any checks payable to FreeBSD, Inc., sent in care of - the following address: - -
- FreeBSD, Inc. - c/o Jordan Hubbard - 4041 Pike Lane, Suite F - Concord - CA, 94520 -
- - (currently using the Walnut Creek CDROM address until a PO box - can be opened) - - Wire transfers may also be sent directly to: - -
- Bank Of America - Concord Main Office - P.O. Box 37176 - San Francisco - CA, 94137-5176 - - Routing #: 121-000-358 - Account #: 01411-07441 (FreeBSD, Inc.) -
- - Any correspondence related to donations should be sent to &a.jkh, - either via email or to the FreeBSD, Inc. postal address given above. - - - If you do not wish to be listed in our donors section, please specify this when - making your donation. Thanks! - - - - Donating hardware - - Donations of hardware in any of the 3 following categories are - also gladly accepted by the FreeBSD Project: - - - - General purpose hardware such as disk drives, memory or - complete systems should be sent to the FreeBSD, Inc. address - listed in the donating funds - section. - - - - 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. - - - - 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. - - - - - - Donating Internet access - - We can always use new mirror sites for FTP, WWW or - cvsup. If you would like to be such a mirror, - please contact the FreeBSD project administrators - admin@FreeBSD.org for more information. - - - - - - Donors Gallery - - The FreeBSD Project is indebted to the following donors and would - like to publically thank them here! - - - - Contributors to the central server - project: - - The following individuals and businesses made it possible for - the FreeBSD Project to build a new central server machine to - eventually replace freefall.FreeBSD.org - by donating the following items: - - - - &a.mbarkah and his employer, - Hemisphere Online, donated a Pentium Pro - (P6) 200Mhz CPU - - - - ASA - Computers donated a Tyan 1662 - motherboard. - - - - Joe McGuckin joe@via.net of ViaNet Communications donated - a Kingston ethernet controller. - - - - Jack O'Neill jack@diamond.xtalwind.net - donated an NCR 53C875 SCSI controller - card. - - - - Ulf Zimmermann ulf@Alameda.net of Alameda Networks donated - 128MB of memory, a 4 Gb disk - drive and the case. - - - - - - Direct funding: - - The following individuals and businesses have generously - contributed direct funding to the project: - - - - Annelise Anderson - ANDRSN@HOOVER.STANFORD.EDU - - - - &a.dillon - - - - Epilogue Technology - Corporation - - - - &a.sef - - - - Don Scott Wilde - - - - Gianmarco Giovannelli - gmarco@masternet.it - - - - Josef C. Grosch joeg@truenorth.org - - - - Robert T. Morris - - - - &a.chuckr - - - - Kenneth P. Stox ken@stox.sa.enteract.com of - Imaginary Landscape, - LLC. - - - - Dmitry S. Kohmanyuk dk@dog.farm.org - - - - Laser5 of Japan - (a portion of the profits from sales of their various FreeBSD - CD-ROMs. - - - - Fuki Shuppan - Publishing Co. donated a portion of their profits from - Hajimete no FreeBSD (FreeBSD, Getting - started) to the FreeBSD and XFree86 projects. - - - - ASCII Corp. - donated a portion of their profits from several FreeBSD-related - books to the FreeBSD project. - - - - Yokogawa Electric - Corp has generously donated significant funding to the - FreeBSD project. - - - - BuffNET - - - - Pacific - Solutions - - - - Siemens AG - via Andre - Albsmeier - - - - Chris Silva - - - - - - - - Hardware contributors: - - The following individuals and businesses have generously - contributed hardware for testing and device driver - development/support: - - - - 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. - - - - TRW Financial Systems, Inc. provided 130 PCs, three 68 GB - fileservers, twelve Ethernets, two routers and an ATM switch for - debugging the diskless code. - - - - Dermot McDonnell donated the Toshiba XM3401B CDROM drive - currently used in freefall. - - - - &a.chuck; contributed his floppy tape streamer for - experimental work. - - - - Larry Altneu larry@ALR.COM, and &a.wilko;, - provided Wangtek and Archive QIC-02 tape drives in order to - improve the wt driver. - - - - Ernst Winter ewinter@lobo.muc.de contributed - a 2.88 MB floppy drive to the project. This will hopefully - increase the pressure for rewriting the floppy disk driver. - ;-) - - - - Tekram - Technologies 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 ftp://ftp.tekram.com/scsi/FreeBSD. - - - - Larry M. Augustin 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! - - - - Christoph Kukulies kuku@FreeBSD.org donated - an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver - development. - - - - - - Special contributors: - - - - Walnut Creek CDROM - has donated almost more than we can say (see the history document for more details). - In particular, we would like to thank them for the original - hardware used for freefall.FreeBSD.org, our primary - development machine, and for thud.FreeBSD.org, 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. - - - - The interface - business GmbH, Dresden 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... - - - - Berkeley Software Design, - Inc. has contributed their DOS emulator code to the - remaining BSD world, which is used in the - doscmd command. - - - - - - - - Core Team Alumni - - 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. - - In rough chronological order: - - - - &a.guido (1995 - 1999) - - - - &a.dyson (1993 - 1998) - - - - &a.nate (1992 - 1996) - - - - &a.rgrimes (1992 - 1995) - - - - Andreas Schulz (1992 - 1995) - - - - &a.csgr (1993 - 1995) - - - - &a.paul (1992 - 1995) - - - - &a.smace (1993 - 1994) - - - - Andrew Moore (1993 - 1994) - - - - Christoph Robitschko (1993 - 1994) - - - - J. T. Conklin (1992 - 1993) - - - - - - Derived Software Contributors - - 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. - - 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. - - - - Additional FreeBSD Contributors - - (in alphabetical order by first name): - - - - ABURAYA Ryushirou rewsirow@ff.iij4u.or.jp - - - - AMAGAI Yoshiji amagai@nue.org - - - - Aaron Bornstein aaronb@j51.com - - - - Aaron Smith aaron@mutex.org - - - - Achim Patzner ap@noses.com - - - - Ada T Lim ada@bsd.org - - - - Adam Baran badam@mw.mil.pl - - - - Adam Glass glass@postgres.berkeley.edu - - - - Adam McDougall mcdouga9@egr.msu.edu - - - - Adrian Colley aecolley@ois.ie - - - - Adrian Hall adrian@ibmpcug.co.uk - - - - Adrian Mariano adrian@cam.cornell.edu - - - - Adrian Steinmann ast@marabu.ch - - - - Adam Strohl troll@digitalspark.net - - - - Adrian T. Filipi-Martin - atf3r@agate.cs.virginia.edu - - - - Ajit Thyagarajan unknown - - - - Akio Morita - amorita@meadow.scphys.kyoto-u.ac.jp - - - - Akira SAWADA unknown - - - - Akira Watanabe - akira@myaw.ei.meisei-u.ac.jp - - - - Akito Fujita fujita@zoo.ncl.omron.co.jp - - - - Alain Kalker - A.C.P.M.Kalker@student.utwente.nl - - - - Alan Bawden alan@curry.epilogue.com - - - - Alec Wolman wolman@cs.washington.edu - - - - Aled Morris aledm@routers.co.uk - - - - Alex garbanzo@hooked.net - - - - Alex D. Chen - dhchen@Canvas.dorm7.nccu.edu.tw - - - - Alex G. Bulushev bag@demos.su - - - - Alex Le Heux alexlh@funk.org - - - - Alex Perel veers@disturbed.net - - - - Alexander B. Povolotsky tarkhil@mgt.msk.ru - - - - Alexander Leidinger - netchild@wurzelausix.CS.Uni-SB.DE - - - - Alexander Langer alex@cichlids.com - - - - Alexandre Snarskii snar@paranoia.ru - - - - Alistair G. Crooks agc@uts.amdahl.com - - - - Allan Saddi asaddi@philosophysw.com - - - - Allen Campbell allenc@verinet.com - - - - Amakawa Shuhei amakawa@hoh.t.u-tokyo.ac.jp - - - - Amancio Hasty hasty@star-gate.com - - - - Amir Farah amir@comtrol.com - - - - Amy Baron amee@beer.org - - - - Anatoly A. Orehovsky tolik@mpeks.tomsk.su - - - - Anatoly Vorobey mellon@pobox.com - - - - Anders Nordby nickerne@nome.no - - - - Anders Thulin Anders.X.Thulin@telia.se - - - - Andras Olah olah@cs.utwente.nl - - - - Andre Albsmeier - Andre.Albsmeier@mchp.siemens.de - - - - Andre Oppermann andre@pipeline.ch - - - - Andreas Haakh ah@alman.robin.de - - - - Andreas Kohout shanee@rabbit.augusta.de - - - - Andreas Lohr andreas@marvin.RoBIN.de - - - - Andreas Schulz unknown - - - - Andreas Wetzel mickey@deadline.snafu.de - - - - Andreas Wrede andreas@planix.com - - - - Andres Vega Garcia unknown - - - - Andrew Atrens atreand@statcan.ca - - - - Andrew Boothman andrew@cream.org - - - - Andrew Gillham gillham@andrews.edu - - - - Andrew Gordon andrew.gordon@net-tel.co.uk - - - - Andrew Herbert andrew@werple.apana.org.au - - - - Andrew J. Korty ajk@purdue.edu - - - - Andrew L. Moore alm@mclink.com - - - - Andrew McRae amcrae@cisco.com - - - - Andrew Stevenson andrew@ugh.net.au - - - - Andrew Timonin tim@pool1.convey.ru - - - - Andrew V. Stesin stesin@elvisti.kiev.ua - - - - Andrew Webster awebster@dataradio.com - - - - Andrey Zakhvatov andy@icc.surw.chel.su - - - - Andy Farkas andyf@speednet.com.au - - - - Andy Valencia ajv@csd.mot.com - - - - Andy Whitcroft andy@sarc.city.ac.uk - - - - Angelo Turetta ATuretta@stylo.it - - - - Anthony C. Chavez magus@xmission.com - - - - Anthony Yee-Hang Chan yeehang@netcom.com - - - - Anton Berezin tobez@plab.ku.dk - - - - Antti Kaipila anttik@iki.fi - - - - Are Bryne are.bryne@communique.no - - - - Ari Suutari ari@suutari.iki.fi - - - - Arjan de Vet devet@IAEhv.nl - - - - Arne Henrik Juul arnej@Lise.Unit.NO - - - - Assar Westerlund assar@sics.se - - - - Atsushi Furuta furuta@sra.co.jp - - - - Atsushi Murai amurai@spec.co.jp - - - - Bakul Shah bvs@bitblocks.com - - - - Barry Bierbauch pivrnec@vszbr.cz - - - - Barry Lustig barry@ictv.com - - - - Ben Hutchinson benhutch@xfiles.org.uk - - - - Ben Jackson unknown - - - - Ben Smithurst ben@scientia.demon.co.uk - - - - Ben Walter bwalter@itachi.swcp.com - - - - Benjamin Lewis bhlewis@gte.net - - - - Bernd Rosauer br@schiele-ct.de - - - - Bill Kish kish@osf.org - - - - Bill Trost trost@cloud.rain.com - - - - Blaz Zupan blaz@amis.net - - - - Bob Van Valzah Bob@whitebarn.com - - - - Bob Willcox bob@luke.pmr.com - - - - Boris Staeblow balu@dva.in-berlin.de - - - - Boyd R. Faulkner faulkner@asgard.bga.com - - - - Brad Karp karp@eecs.harvard.edu - - - - Bradley Dunn bradley@dunn.org - - - - Brandon Fosdick bfoz@glue.umd.edu - - - - Brandon Gillespie brandon@roguetrader.com - - - - &a.wlloyd - - - - Bob Wilcox bob@obiwan.uucp - - - - Boyd Faulkner faulkner@mpd.tandem.com - - - - Brent J. Nordquist bjn@visi.com - - - - Brett Lymn blymn@mulga.awadi.com.AU - - - - Brett Taylor - brett@peloton.physics.montana.edu - - - - Brian Campbell brianc@pobox.com - - - - Brian Clapper bmc@willscreek.com - - - - Brian Cully shmit@kublai.com - - - - Brian Handy - handy@lambic.space.lockheed.com - - - - Brian Litzinger brian@MediaCity.com - - - - Brian McGovern bmcgover@cisco.com - - - - Brian Moore ziff@houdini.eecs.umich.edu - - - - Brian R. Haug haug@conterra.com - - - - Brian Tao taob@risc.org - - - - Brion Moss brion@queeg.com - - - - Bruce A. Mah bmah@ca.sandia.gov - - - - Bruce Albrecht bruce@zuhause.mn.org - - - - Bruce Gingery bgingery@gtcs.com - - - - Bruce J. Keeler loodvrij@gridpoint.com - - - - Bruce Murphy packrat@iinet.net.au - - - - Bruce Walter walter@fortean.com - - - - Carey Jones mcj@acquiesce.org - - - - Carl Fongheiser cmf@netins.net - - - - Carl Mascott cmascott@world.std.com - - - - Casper casper@acc.am - - - - Castor Fu castor@geocast.com - - - - Cejka Rudolf cejkar@dcse.fee.vutbr.cz - - - - Chain Lee chain@110.net - - - - Charles Hannum mycroft@ai.mit.edu - - - - Charles Henrich henrich@msu.edu - - - - Charles Mott cmott@srv.net - - - - Charles Owens owensc@enc.edu - - - - Chet Ramey chet@odin.INS.CWRU.Edu - - - - Chia-liang Kao clkao@CirX.ORG - - - - Chiharu Shibata chi@bd.mbn.or.jp - - - - Chip Norkus unknown - - - - Choi Jun Ho junker@jazz.snu.ac.kr - - - - Chris Csanady cc@tarsier.ca.sandia.gov - - - - Chris Dabrowski chris@vader.org - - - - Chris Dillon cdillon@wolves.k12.mo.us - - - - Chris Shenton - cshenton@angst.it.hq.nasa.gov - - - - Chris Stenton jacs@gnome.co.uk - - - - Chris Timmons skynyrd@opus.cts.cwu.edu - - - - Chris Torek torek@ee.lbl.gov - - - - Christian Gusenbauer - cg@fimp01.fim.uni-linz.ac.at - - - - Christian Haury Christian.Haury@sagem.fr - - - - Christian Weisgerber - naddy@bigeye.rhein-neckar.de - - - - Christoph P. Kukulies kuku@FreeBSD.org - - - - Christoph Robitschko - chmr@edvz.tu-graz.ac.at - - - - Christoph Weber-Fahr - wefa@callcenter.systemhaus.net - - - - Christopher G. Demetriou - cgd@postgres.berkeley.edu - - - - Christopher T. Johnson - cjohnson@neunacht.netgsi.com - - - - Chrisy Luke chrisy@flix.net - - - - Chuck Hein chein@cisco.com - - - - Clive Lin clive@CiRX.ORG - - - - Colman Reilly careilly@tcd.ie - - - - Conrad Sabatier conrads@neosoft.com - - - - Coranth Gryphon gryphon@healer.com - - - - Cornelis van der Laan - nils@guru.ims.uni-stuttgart.de - - - - Cove Schneider cove@brazil.nbn.com - - - - Craig Leres leres@ee.lbl.gov - - - - Craig Loomis unknown - - - - Craig Metz cmetz@inner.net - - - - Craig Spannring cts@internetcds.com - - - - Craig Struble cstruble@vt.edu - - - - Cristian Ferretti cfs@riemann.mat.puc.cl - - - - Curt Mayer curt@toad.com - - - - Cy Schubert cschuber@uumail.gov.bc.ca - - - - DI. Christian Gusenbauer - cg@scotty.edvz.uni-linz.ac.at - - - - Dai Ishijima ishijima@tri.pref.osaka.jp - - - - Damian Hamill damian@cablenet.net - - - - Dan Cross tenser@spitfire.ecsel.psu.edu - - - - Dan Lukes dan@obluda.cz - - - - Dan Nelson dnelson@emsphone.com - - - - Dan Walters hannibal@cyberstation.net - - - - Daniel M. Eischen - deischen@iworks.InterWorks.org - - - - Daniel O'Connor doconnor@gsoft.com.au - - - - Daniel Poirot poirot@aio.jsc.nasa.gov - - - - Daniel Rock rock@cs.uni-sb.de - - - - Danny Egen unknown - - - - Danny J. Zerkel dzerkel@phofarm.com - - - - Darren Reed avalon@coombs.anu.edu.au - - - - Dave Adkins adkin003@tc.umn.edu - - - - Dave Andersen angio@aros.net - - - - Dave Blizzard dblizzar@sprynet.com - - - - Dave Bodenstab imdave@synet.net - - - - Dave Burgess burgess@hrd769.brooks.af.mil - - - - Dave Chapeskie dchapes@ddm.on.ca - - - - Dave Cornejo dave@dogwood.com - - - - Dave Edmondson davided@sco.com - - - - Dave Glowacki dglo@ssec.wisc.edu - - - - Dave Marquardt marquard@austin.ibm.com - - - - Dave Tweten tweten@FreeBSD.org - - - - David A. Adkins adkin003@tc.umn.edu - - - - David A. Bader dbader@umiacs.umd.edu - - - - David Borman dab@bsdi.com - - - - David Dawes dawes@XFree86.org - - - - David Filo filo@yahoo.com - - - - David Holland dholland@eecs.harvard.edu - - - - David Holloway daveh@gwythaint.tamis.com - - - - David Horwitt dhorwitt@ucsd.edu - - - - David Hovemeyer daveho@infocom.com - - - - David Jones dej@qpoint.torfree.net - - - - David Kelly dkelly@tomcat1.tbe.com - - - - David Kulp dkulp@neomorphic.com - - - - David L. Nugent davidn@blaze.net.au - - - - David Leonard d@scry.dstc.edu.au - - - - David Malone dwmalone@maths.tcd.ie - - - - David Muir Sharnoff muir@idiom.com - - - - David S. Miller davem@jenolan.rutgers.edu - - - - David Wolfskill dhw@whistle.com - - - - Dean Gaudet dgaudet@arctic.org - - - - Dean Huxley dean@fsa.ca - - - - Denis Fortin unknown - - - - Dennis Glatting - dennis.glatting@software-munitions.com - - - - Denton Gentry denny1@home.com - - - - Derek Inksetter derek@saidev.com - - - - Dima Sivachenko dima@Chg.RU - - - - Dirk Keunecke dk@panda.rhein-main.de - - - - Dirk Nehrling nerle@pdv.de - - - - Dmitry Khrustalev dima@xyzzy.machaon.ru - - - - Dmitry Kohmanyuk dk@farm.org - - - - Dom Mitchell dom@myrddin.demon.co.uk - - - - Dominik Brettnacher domi@saargate.de - - - - Don Croyle croyle@gelemna.ft-wayne.in.us - - - - &a.whiteside; - - - - Don Morrison dmorrisn@u.washington.edu - - - - Don Yuniskis dgy@rtd.com - - - - Donald Maddox dmaddox@conterra.com - - - - Doug Barton studded@dal.net - - - - Douglas Ambrisko ambrisko@whistle.com - - - - Douglas Carmichael dcarmich@mcs.com - - - - Douglas Crosher dtc@scrooge.ee.swin.oz.au - - - - Drew Derbyshire ahd@kew.com - - - - Duncan Barclay dmlb@ragnet.demon.co.uk - - - - Dustin Sallings dustin@spy.net - - - - Eckart "Isegrim" Hofmann - Isegrim@Wunder-Nett.org - - - - Ed Gold - vegold01@starbase.spd.louisville.edu - - - - Ed Hudson elh@p5.spnet.com - - - - Edward Wang edward@edcom.com - - - - Edwin Groothus edwin@nwm.wan.philips.com - - - - Eiji-usagi-MATSUmoto usagi@clave.gr.jp - - - - ELISA Font Project - - - - Elmar Bartel - bartel@informatik.tu-muenchen.de - - - - Eric A. Griff eagriff@global2000.net - - - - Eric Blood eblood@cs.unr.edu - - - - Eric J. Haug ejh@slustl.slu.edu - - - - Eric J. Schwertfeger eric@cybernut.com - - - - Eric L. Hernes erich@lodgenet.com - - - - Eric P. Scott eps@sirius.com - - - - Eric Sprinkle eric@ennovatenetworks.com - - - - Erich Stefan Boleyn erich@uruk.org - - - - Erik E. Rantapaa rantapaa@math.umn.edu - - - - Erik H. Moe ehm@cris.com - - - - Ernst Winter ewinter@lobo.muc.de - - - - Espen Skoglund espensk@stud.cs.uit.no> - - - - Eugene M. Kim astralblue@usa.net - - - - Eugene Radchenko genie@qsar.chem.msu.su - - - - Evan Champion evanc@synapse.net - - - - Faried Nawaz fn@Hungry.COM - - - - Flemming Jacobsen fj@tfs.com - - - - Fong-Ching Liaw fong@juniper.net - - - - Francis M J Hsieh mjshieh@life.nthu.edu.tw - - - - Frank Bartels knarf@camelot.de - - - - Frank Chen Hsiung Chan - frankch@waru.life.nthu.edu.tw - - - - Frank Durda IV uhclem@nemesis.lonestar.org - - - - Frank MacLachlan fpm@n2.net - - - - Frank Nobis fn@Radio-do.de - - - - Frank Volf volf@oasis.IAEhv.nl - - - - Frank ten Wolde franky@pinewood.nl - - - - Frank van der Linden frank@fwi.uva.nl - - - - Fred Cawthorne fcawth@jjarray.umn.edu - - - - Fred Gilham gilham@csl.sri.com - - - - Fred Templin templin@erg.sri.com - - - - Frederick Earl Gray fgray@rice.edu - - - - FUJIMOTO Kensaku - fujimoto@oscar.elec.waseda.ac.jp - - - - FUJISHIMA Satsuki k5@respo.or.jp - - - - FURUSAWA Kazuhisa - furusawa@com.cs.osakafu-u.ac.jp - - - - Gabor Kincses gabor@acm.org - - - - Gabor Zahemszky zgabor@CoDe.hu - - - - G. Adam Stanislavadam@whizkidtech.net - - - - Garance A Drosehn gad@eclipse.its.rpi.edu - - - - Gareth McCaughan gjm11@dpmms.cam.ac.uk - - - - Gary A. Browning gab10@griffcd.amdahl.com - - - - Gary Howland gary@hotlava.com - - - - Gary J. garyj@rks32.pcs.dec.com - - - - Gary Kline kline@thought.org - - - - Gaspar Chilingarov nightmar@lemming.acc.am - - - - Gea-Suan Lin gsl@tpts4.seed.net.tw - - - - Geoff Rehmet csgr@alpha.ru.ac.za - - - - Georg Wagner georg.wagner@ubs.com - - - - Gerard Roudier groudier@club-internet.fr - - - - Gianmarco Giovannelli - gmarco@giovannelli.it - - - - Gil Kloepfer Jr. gil@limbic.ssdl.com - - - - Gilad Rom rom_glsa@ein-hashofet.co.il - - - - Ginga Kawaguti - ginga@amalthea.phys.s.u-tokyo.ac.jp - - - - Giles Lean giles@nemeton.com.au - - - - Glen Foster gfoster@gfoster.com - - - - Glenn Johnson gljohns@bellsouth.net - - - - Godmar Back gback@facility.cs.utah.edu - - - - Goran Hammarback goran@astro.uu.se - - - - Gord Matzigkeit gord@enci.ucalgary.ca - - - - Gordon Greeff gvg@uunet.co.za - - - - Graham Wheeler gram@cdsec.com - - - - Greg A. Woods woods@zeus.leitch.com - - - - Greg Ansley gja@ansley.com - - - - Greg Troxel gdt@ir.bbn.com - - - - Greg Ungerer gerg@stallion.oz.au - - - - Gregory Bond gnb@itga.com.au - - - - Gregory D. Moncreaff - moncrg@bt340707.res.ray.com - - - - Guy Harris guy@netapp.com - - - - Guy Helmer ghelmer@cs.iastate.edu - - - - HAMADA Naoki hamada@astec.co.jp - - - - HONDA Yasuhiro - honda@kashio.info.mie-u.ac.jp - - - - HOSOBUCHI Noriyuki hoso@buchi.tama.or.jp - - - - Hannu Savolainen hannu@voxware.pp.fi - - - - Hans Huebner hans@artcom.de - - - - Hans Petter Bieker zerium@webindex.no - - - - Hans Zuidam hans@brandinnovators.com - - - - Harlan Stenn Harlan.Stenn@pfcs.com - - - - Harold Barker hbarker@dsms.com - - - - Havard Eidnes - Havard.Eidnes@runit.sintef.no - - - - Heikki Suonsivu hsu@cs.hut.fi - - - - Heiko W. Rupp unknown - - - - Helmut F. Wirth hfwirth@ping.at - - - - Henrik Vestergaard Draboel - hvd@terry.ping.dk - - - - Herb Peyerl hpeyerl@NetBSD.org - - - - Hideaki Ohmon ohmon@tom.sfc.keio.ac.jp - - - - Hidekazu Kuroki hidekazu@cs.titech.ac.jp - - - - Hideki Yamamoto hyama@acm.org - - - - Hideyuki Suzuki - hideyuki@sat.t.u-tokyo.ac.jp - - - - Hirayama Issei iss@mail.wbs.ne.jp - - - - Hiroaki Sakai sakai@miya.ee.kagu.sut.ac.jp - - - - Hiroharu Tamaru tamaru@ap.t.u-tokyo.ac.jp - - - - Hironori Ikura hikura@kaisei.org - - - - Hiroshi Nishikawa nis@pluto.dti.ne.jp - - - - Hiroya Tsubakimoto unknown - - - - Holger Veit Holger.Veit@gmd.de - - - - Holm Tiffe holm@geophysik.tu-freiberg.de - - - - Horance Chou - horance@freedom.ie.cycu.edu.tw - - - - Horihiro Kumagai kuma@jp.FreeBSD.org - - - - HOTARU-YA hotaru@tail.net - - - - Hr.Ladavac lada@ws2301.gud.siemens.co.at - - - - Hubert Feyrer hubertf@NetBSD.ORG - - - - Hugh F. Mahon hugh@nsmdserv.cnd.hp.com - - - - Hugh Mahon h_mahon@fc.hp.com - - - - Hung-Chi Chu hcchu@r350.ee.ntu.edu.tw - - - - IMAI Takeshi take-i@ceres.dti.ne.jp - - - - IMAMURA Tomoaki - tomoak-i@is.aist-nara.ac.jp - - - - Ian Dowse iedowse@maths.tcd.ie - - - - Ian Holland ianh@tortuga.com.au - - - - Ian Struble ian@broken.net - - - - Ian Vaudrey i.vaudrey@bigfoot.com - - - - Igor Khasilev igor@jabber.paco.odessa.ua - - - - Igor Roshchin str@giganda.komkon.org - - - - Igor Sviridov siac@ua.net - - - - Igor Vinokurov igor@zynaps.ru - - - - Ikuo Nakagawa ikuo@isl.intec.co.jp - - - - Ilya V. Komarov mur@lynx.ru - - - - Issei Suzuki issei@jp.FreeBSD.org - - - - Itsuro Saito saito@miv.t.u-tokyo.ac.jp - - - - J. Bryant jbryant@argus.flash.net - - - - J. David Lowe lowe@saturn5.com - - - - J. Han hjh@best.com - - - - J. Hawk jhawk@MIT.EDU - - - - J.T. Conklin jtc@cygnus.com - - - - J.T. Jang keith@email.gcn.net.tw - - - - Jack jack@zeus.xtalwind.net - - - - Jacob Bohn Lorensen jacob@jblhome.ping.mk - - - - Jagane D Sundar jagane@netcom.com - - - - Jake Burkholder jake@checker.org - - - - Jake Hamby jehamby@lightside.com - - - - James Clark jjc@jclark.com - - - - James D. Stewart jds@c4systm.com - - - - James Jegers jimj@miller.cs.uwm.edu - - - - James Raynard - fhackers@jraynard.demon.co.uk - - - - James T. Liu jtliu@phlebas.rockefeller.edu - - - - James da Silva jds@cs.umd.edu - - - - Jan Conard - charly@fachschaften.tu-muenchen.de - - - - Jan Koum jkb@FreeBSD.org - - - - Janick Taillandier - Janick.Taillandier@ratp.fr - - - - Janusz Kokot janek@gaja.ipan.lublin.pl - - - - Jarle Greipsland jarle@idt.unit.no - - - - Jason Garman init@risen.org - - - - Jason Thorpe thorpej@NetBSD.org - - - - Jason Wright jason@OpenBSD.org - - - - Jason Young - doogie@forbidden-donut.anet-stl.com - - - - Javier Martin Rueda jmrueda@diatel.upm.es - - - - Jay Fenlason hack@datacube.com - - - - Jaye Mathisen mrcpu@cdsnet.net - - - - Jeff Bartig jeffb@doit.wisc.edu - - - - Jeff Forys jeff@forys.cranbury.nj.us - - - - Jeff Kletsky Jeff@Wagsky.com - - - - Jeffrey Evans evans@scnc.k12.mi.us - - - - Jeffrey Wheat jeff@cetlink.net - - - - Jens Schweikhardt schweikh@noc.dfn.d - - - - Jeremy Allison jallison@whistle.com - - - - Jeremy Chatfield jdc@xinside.com - - - - Jeremy Lea reg@shale.csir.co.za - - - - Jeremy Prior unknown - - - - Jeroen Ruigrok/Asmodai asmodai@wxs.nl - - - - Jesse Rosenstock jmr@ugcs.caltech.edu - - - - Jian-Da Li jdli@csie.nctu.edu.tw - - - - Jim Babb babb@FreeBSD.org - - - - Jim Binkley jrb@cs.pdx.edu - - - - Jim Carroll jim@carroll.com - - - - Jim Flowers jflowers@ezo.net - - - - Jim Leppek jleppek@harris.com - - - - Jim Lowe james@cs.uwm.edu - - - - Jim Mattson jmattson@sonic.net - - - - Jim Mercer jim@komodo.reptiles.org - - - - Jim Wilson wilson@moria.cygnus.com - - - - Jimbo Bahooli - griffin@blackhole.iceworld.org - - - - Jin Guojun jin@george.lbl.gov - - - - Joachim Kuebart unknown - - - - Joao Carlos Mendes Luis jonny@jonny.eng.br - - - - Jochen Pohl jpo.drs@sni.de - - - - Joe "Marcus" Clarke marcus@miami.edu - - - - Joe Abley jabley@clear.co.nz - - - - Joe Jih-Shian Lu jslu@dns.ntu.edu.tw - - - - Joe Orthoefer j_orthoefer@tia.net - - - - Joe Traister traister@mojozone.org - - - - Joel Faedi Joel.Faedi@esial.u-nancy.fr - - - - Joel Ray Holveck joelh@gnu.org - - - - Joel Sutton sutton@aardvark.apana.org.au - - - - Johan Granlund johan@granlund.nu - - - - Johan Karlsson k@numeri.campus.luth.se - - - - Johan Larsson johan@moon.campus.luth.se - - - - Johann Tonsing jtonsing@mikom.csir.co.za - - - - Johannes Helander unknown - - - - Johannes Stille unknown - - - - John Baldwin jobaldwi@vt.edu - - - - John Beckett jbeckett@southern.edu - - - - John Beukema jbeukema@hk.super.net - - - - John Brezak unknown - - - - John Capo jc@irbs.com - - - - John F. Woods jfw@jfwhome.funhouse.com - - - - John Goerzen - jgoerzen@alexanderwohl.complete.org - - - - John Hay jhay@mikom.csir.co.za - - - - John Heidemann johnh@isi.edu - - - - John Hood cgull@owl.org - - - - John Kohl unknown - - - - John Lind john@starfire.mn.org - - - - John Mackin john@physiol.su.oz.au - - - - John P johnp@lodgenet.com - - - - John Perry perry@vishnu.alias.net - - - - John Preisler john@vapornet.com - - - - John Rochester jr@cs.mun.ca - - - - John Sadler john_sadler@alum.mit.edu - - - - John Saunders john@pacer.nlc.net.au - - - - John W. DeBoskey jwd@unx.sas.com - - - - John Wehle john@feith.com - - - - John Woods jfw@eddie.mit.edu - - - - Jon Morgan morgan@terminus.trailblazer.com - - - - Jonathan H N Chin jc254@newton.cam.ac.uk - - - - Jonathan Hanna - jh@pc-21490.bc.rogers.wave.ca - - - - Jorge Goncalves j@bug.fe.up.pt - - - - Jorge M. Goncalves ee96199@tom.fe.up.pt - - - - Jos Backus jbackus@plex.nl - - - - Jose M. Alcaide jose@we.lc.ehu.es - - - - Jose Marques jose@nobody.org - - - - Josef Grosch - jgrosch@superior.mooseriver.com - - - - Josef Karthauser joe@uk.FreeBSD.org - - - - Joseph Stein joes@wstein.com - - - - Josh Gilliam josh@quick.net - - - - Josh Tiefenbach josh@ican.net - - - - Juergen Lock nox@jelal.hb.north.de - - - - Juha Inkari inkari@cc.hut.fi - - - - Jukka A. Ukkonen jua@iki.fi - - - - Julian Assange proff@suburbia.net - - - - Julian Coleman j.d.coleman@ncl.ac.uk - - - - &a.jhs - - - - Julian Jenkins kaveman@magna.com.au - - - - Junichi Satoh junichi@jp.FreeBSD.org - - - - Junji SAKAI sakai@jp.FreeBSD.org - - - - Junya WATANABE junya-w@remus.dti.ne.jp - - - - K.Higashino a00303@cc.hc.keio.ac.jp - - - - KUNISHIMA Takeo kunishi@c.oka-pu.ac.jp - - - - Kai Vorma vode@snakemail.hut.fi - - - - Kaleb S. Keithley kaleb@ics.com - - - - Kaneda Hiloshi vanitas@ma3.seikyou.ne.jp - - - - Kapil Chowksey kchowksey@hss.hns.com - - - - Karl Denninger karl@mcs.com - - - - Karl Dietz Karl.Dietz@triplan.com - - - - Karl Lehenbauer karl@NeoSoft.com - - - - Kato Takenori - kato@eclogite.eps.nagoya-u.ac.jp - - - - Kawanobe Koh kawanobe@st.rim.or.jp - - - - Kazuhiko Kiriyama kiri@kiri.toba-cmt.ac.jp - - - - Kazuo Horikawa horikawa@jp.FreeBSD.org - - - - Kees Jan Koster kjk1@ukc.ac.uk - - - - Keith Bostic bostic@bostic.com - - - - Keith E. Walker unknown - - - - Keith Moore unknown - - - - Keith Sklower unknown - - - - Kelly Yancey kbyanc@posi.net - - - - Ken Hornstein unknown - - - - Ken Key key@cs.utk.edu - - - - Ken Mayer kmayer@freegate.com - - - - Kenji Saito marukun@mx2.nisiq.net - - - - Kenji Tomita tommyk@da2.so-net.or.jp - - - - Kenneth Furge kenneth.furge@us.endress.com - - - - Kenneth Monville desmo@bandwidth.org - - - - Kenneth R. Westerback krw@tcn.net - - - - Kenneth Stailey kstailey@gnu.ai.mit.edu - - - - Kent Talarico kent@shipwreck.tsoft.net - - - - Kent Vander Velden graphix@iastate.edu - - - - Kentaro Inagaki JBD01226@niftyserve.ne.jp - - - - Kevin Bracey kbracey@art.acorn.co.uk - - - - Kevin Day toasty@dragondata.com - - - - Kevin Lahey kml@nas.nasa.gov - - - - Kevin Lokevlo@hello.com.tw - - - - Kevin Street street@iname.com - - - - Kevin Van Maren vanmaren@fast.cs.utah.edu - - - - Kiroh HARADA kiroh@kh.rim.or.jp - - - - Klaus Klein kleink@layla.inka.de - - - - Klaus-J. Wolf Yanestra@t-online.de - - - - Koichi Sato copan@ppp.fastnet.or.jp - - - - Kostya Lukin lukin@okbmei.msk.su - - - - Kouichi Hirabayashi kh@mogami-wire.co.jp - - - - Kurt D. Zeilenga Kurt@Boolean.NET - - - - Kurt Olsen kurto@tiny.mcs.usu.edu - - - - L. Jonas Olsson - ljo@ljo-slip.DIALIN.CWRU.Edu - - - - Lars Köller - Lars.Koeller@Uni-Bielefeld.DE - - - - Larry Altneu larry@ALR.COM - - - - Laurence Lopez lopez@mv.mv.com - - - - Lee Cremeans lcremean@tidalwave.net - - - - Liang Tai-hwa - avatar@www.mmlab.cse.yzu.edu.tw - - - - Lon Willett lon%softt.uucp@math.utah.edu - - - - Louis A. Mamakos louie@TransSys.COM - - - - Louis Mamakos loiue@TransSys.com - - - - Lucas James Lucas.James@ldjpc.apana.org.au - - - - Lyndon Nerenberg lyndon@orthanc.com - - - - M.C. Wong unknown - - - - MANTANI Nobutaka nobutaka@nobutaka.com - - - - MIHIRA Sanpei Yoshiro sanpei@sanpei.org - - - - MITA Yoshio mita@jp.FreeBSD.org - - - - MITSUNAGA Noriaki - mitchy@er.ams.eng.osaka-u.ac.jp - - - - MOROHOSHI Akihiko moro@race.u-tokyo.ac.jp - - - - Magnus Enbom dot@tinto.campus.luth.se - - - - Mahesh Neelakanta mahesh@gcomm.com - - - - Makoto MATSUSHITA matusita@jp.FreeBSD.org - - - - Makoto WATANABE - watanabe@zlab.phys.nagoya-u.ac.jp - - - - Malte Lance malte.lance@gmx.net - - - - Manu Iyengar - iyengar@grunthos.pscwa.psca.com - - - - Marc Frajola marc@dev.com - - - - Marc Ramirez mrami@mramirez.sy.yale.edu - - - - Marc Slemko marcs@znep.com - - - - Marc van Kempen wmbfmk@urc.tue.nl - - - - Marc van Woerkom van.woerkom@netcologne.de - - - - Marcel Moolenaar marcel@scc.nl - - - - Mario Sergio Fujikawa Ferreira - lioux@gns.com.br - - - - Mark Andrews unknown - - - - Mark Cammidge mark@gmtunx.ee.uct.ac.za - - - - Mark Diekhans markd@grizzly.com - - - - Mark Huizer xaa@stack.nl - - - - Mark J. Taylor mtaylor@cybernet.com - - - - Mark Krentel krentel@rice.edu - - - - Mark Mayo markm@vmunix.com - - - - Mark Thompson thompson@tgsoft.com - - - - Mark Tinguely tinguely@plains.nodak.edu - - - - Mark Treacy unknown - - - - Mark Valentine mark@linus.demon.co.uk - - - - Martin Birgmeier - - - - Martin Ibert mib@ppe.bb-data.de - - - - Martin Kammerhofer dada@sbox.tu-graz.ac.at - - - - Martin Renters martin@tdc.on.ca - - - - Martti Kuparinen - martti.kuparinen@ericsson.com - - - - Masachika ISHIZUKA - ishizuka@isis.min.ntt.jp - - - - Mas.TAKEMURA unknown - - - - Masafumi NAKANE max@wide.ad.jp - - - - Masahiro Sekiguchi - seki@sysrap.cs.fujitsu.co.jp - - - - Masanobu Saitoh msaitoh@spa.is.uec.ac.jp - - - - Masanori Kanaoka kana@saijo.mke.mei.co.jp - - - - Masanori Kiriake seiken@ARGV.AC - - - - Masatoshi TAMURA - tamrin@shinzan.kuee.kyoto-u.ac.jp - - - - Mats Lofkvist mal@algonet.se - - - - Matt Bartley mbartley@lear35.cytex.com - - - - Matt Thomas matt@3am-software.com - - - - Matt White mwhite+@CMU.EDU - - - - Matthew C. Mead mmead@Glock.COM - - - - Matthew Cashdollar mattc@rfcnet.com - - - - Matthew Flatt mflatt@cs.rice.edu - - - - Matthew Fuller fullermd@futuresouth.com - - - - Matthew Stein matt@bdd.net - - - - Matthias Pfaller leo@dachau.marco.de - - - - Matthias Scheler tron@netbsd.org - - - - Mattias Gronlund - Mattias.Gronlund@sa.erisoft.se - - - - Mattias Pantzare pantzer@ludd.luth.se - - - - Maurice Castro - maurice@planet.serc.rmit.edu.au - - - - Max Euston meuston@jmrodgers.com - - - - Max Khon fjoe@husky.iclub.nsu.ru - - - - Maxim Bolotin max@rsu.ru - - - - Maxim V. Sobolev sobomax@altavista.net - - - - Micha Class - michael_class@hpbbse.bbn.hp.com - - - - Michael Butler imb@scgt.oz.au - - - - Michael Butschky butsch@computi.erols.com - - - - Michael Clay mclay@weareb.org - - - - Michael Elbel me@FreeBSD.org - - - - Michael Galassi nerd@percival.rain.com - - - - Michael Hancock michaelh@cet.co.jp - - - - Michael Hohmuth hohmuth@inf.tu-dresden.de - - - - Michael Perlman canuck@caam.rice.edu - - - - Michael Petry petry@netwolf.NetMasters.com - - - - Michael Reifenberger root@totum.plaut.de - - - - Michael Sardo jaeger16@yahoo.com - - - - Michael Searle searle@longacre.demon.co.uk - - - - Michal Listos mcl@Amnesiac.123.org - - - - Michio Karl Jinbo - karl@marcer.nagaokaut.ac.jp - - - - Miguel Angel Sagreras - msagre@cactus.fi.uba.ar - - - - Mihoko Tanaka m_tonaka@pa.yokogawa.co.jp - - - - Mika Nystrom mika@cs.caltech.edu - - - - Mikael Hybsch micke@dynas.se - - - - Mikael Karpberg - karpen@ocean.campus.luth.se - - - - Mike Del repenting@hotmail.com - - - - Mike Durian durian@plutotech.com - - - - Mike Durkin mdurkin@tsoft.sf-bay.org - - - - Mike E. Matsnev mike@azog.cs.msu.su - - - - Mike Evans mevans@candle.com - - - - Mike Grupenhoff kashmir@umiacs.umd.edu - - - - Mike Hibler mike@marker.cs.utah.edu - - - - Mike Karels unknown - - - - Mike McGaughey mmcg@cs.monash.edu.au - - - - Mike Meyer mwm@shiva.the-park.com - - - - Mike Mitchell mitchell@ref.tfs.com - - - - Mike Murphy mrm@alpharel.com - - - - Mike Peck mike@binghamton.edu - - - - Mike Spengler mks@msc.edu - - - - Mikhail A. Sokolov mishania@demos.su - - - - Mikhail Teterin mi@aldan.ziplink.net - - - - Ming-I Hseh PA@FreeBSD.ee.Ntu.edu.TW - - - - Mitsuru IWASAKI iwasaki@pc.jaring.my - - - - Mitsuru Yoshida mitsuru@riken.go.jp - - - - Monte Mitzelfelt monte@gonefishing.org - - - - Morgan Davis root@io.cts.com - - - - Mostyn Lewis mostyn@mrl.com - - - - Motomichi Matsuzaki mzaki@e-mail.ne.jp - - - - Motoyuki Kasahara m-kasahr@sra.co.jp - - - - Motoyuki Konno motoyuki@snipe.rim.or.jp - - - - Murray Stokely murray@cdrom.com - - - - N.G.Smith ngs@sesame.hensa.ac.uk - - - - NAGAO Tadaaki nagao@cs.titech.ac.jp - - - - NAKAJI Hiroyuki - nakaji@tutrp.tut.ac.jp - - - - NAKAMURA Kazushi nkazushi@highway.or.jp - - - - NAKAMURA Motonori - motonori@econ.kyoto-u.ac.jp - - - - NIIMI Satoshi sa2c@and.or.jp - - - - NOKUBI Hirotaka h-nokubi@yyy.or.jp - - - - Nadav Eiron nadav@barcode.co.il - - - - Nanbor Wang nw1@cs.wustl.edu - - - - Naofumi Honda - honda@Kururu.math.sci.hokudai.ac.jp - - - - Naoki Hamada nao@tom-yam.or.jp - - - - Narvi narvi@haldjas.folklore.ee - - - - Nathan Ahlstrom nrahlstr@winternet.com - - - - Nathan Dorfman nathan@rtfm.net - - - - Neal Fachan kneel@ishiboo.com - - - - Neil Blakey-Milner nbm@rucus.ru.ac.za - - - - Niall Smart rotel@indigo.ie - - - - Nick Barnes Nick.Barnes@pobox.com - - - - Nick Handel nhandel@NeoSoft.com - - - - Nick Hilliard nick@foobar.org - - - - &a.nsayer; - - - - Nick Williams njw@cs.city.ac.uk - - - - Nickolay N. Dudorov nnd@itfs.nsk.su - - - - Niklas Hallqvist niklas@filippa.appli.se - - - - Nisha Talagala nisha@cs.berkeley.edu - - - - No Name ZW6T-KND@j.asahi-net.or.jp - - - - No Name adrian@virginia.edu - - - - No Name alex@elvisti.kiev.ua - - - - No Name anto@netscape.net - - - - No Name bobson@egg.ics.nitch.ac.jp - - - - No Name bovynf@awe.be - - - - No Name burg@is.ge.com - - - - No Name chris@gnome.co.uk - - - - No Name colsen@usa.net - - - - No Name coredump@nervosa.com - - - - No Name dannyman@arh0300.urh.uiuc.edu - - - - No Name davids@SECNET.COM - - - - No Name derek@free.org - - - - No Name devet@adv.IAEhv.nl - - - - No Name djv@bedford.net - - - - No Name dvv@sprint.net - - - - No Name enami@ba2.so-net.or.jp - - - - No Name flash@eru.tubank.msk.su - - - - No Name flash@hway.ru - - - - No Name fn@pain.csrv.uidaho.edu - - - - No Name gclarkii@netport.neosoft.com - - - - No Name gordon@sheaky.lonestar.org - - - - No Name graaf@iae.nl - - - - No Name greg@greg.rim.or.jp - - - - No Name grossman@cygnus.com - - - - No Name gusw@fub46.zedat.fu-berlin.de - - - - No Name hfir@math.rochester.edu - - - - No Name hnokubi@yyy.or.jp - - - - No Name iaint@css.tuu.utas.edu.au - - - - No Name invis@visi.com - - - - No Name ishisone@sra.co.jp - - - - No Name iverson@lionheart.com - - - - No Name jpt@magic.net - - - - No Name junker@jazz.snu.ac.kr - - - - No Name k-sugyou@ccs.mt.nec.co.jp - - - - No Name kenji@reseau.toyonaka.osaka.jp - - - - No Name kfurge@worldnet.att.net - - - - No Name lh@aus.org - - - - No Name lhecking@nmrc.ucc.ie - - - - No Name mrgreen@mame.mu.oz.au - - - - No Name nakagawa@jp.FreeBSD.org - - - - No Name ohki@gssm.otsuka.tsukuba.ac.jp - - - - No Name owaki@st.rim.or.jp - - - - No Name pechter@shell.monmouth.com - - - - No Name pete@pelican.pelican.com - - - - No Name pritc003@maroon.tc.umn.edu - - - - No Name risner@stdio.com - - - - No Name roman@rpd.univ.kiev.ua - - - - No Name root@ns2.redline.ru - - - - No Name root@uglabgw.ug.cs.sunysb.edu - - - - No Name stephen.ma@jtec.com.au - - - - No Name sumii@is.s.u-tokyo.ac.jp - - - - No Name takas-su@is.aist-nara.ac.jp - - - - No Name tamone@eig.unige.ch - - - - No Name tjevans@raleigh.ibm.com - - - - No Name tony-o@iij.ad.jp amurai@spec.co.jp - - - - No Name torii@tcd.hitachi.co.jp - - - - No Name uenami@imasy.or.jp - - - - No Name uhlar@netlab.sk - - - - No Name vode@hut.fi - - - - No Name wlloyd@mpd.ca - - - - No Name wlr@furball.wellsfargo.com - - - - No Name wmbfmk@urc.tue.nl - - - - No Name yamagata@nwgpc.kek.jp - - - - No Name ziggy@ryan.org - - - - Nobuhiro Yasutomi nobu@psrc.isac.co.jp - - - - Nobuyuki Koganemaru - kogane@koganemaru.co.jp - - - - Norio Suzuki nosuzuki@e-mail.ne.jp - - - - Noritaka Ishizumi graphite@jp.FreeBSD.org - - - - Noriyuki Soda soda@sra.co.jp - - - - Oh Junseon hollywar@mail.holywar.net - - - - Olaf Wagner wagner@luthien.in-berlin.de - - - - Oleg Sharoiko os@rsu.ru - - - - Oleg V. Volkov rover@lglobus.ru - - - - Oliver Breuninger ob@seicom.NET - - - - Oliver Friedrichs oliver@secnet.com - - - - Oliver Fromme - oliver.fromme@heim3.tu-clausthal.de - - - - Oliver Laumann - net@informatik.uni-bremen.de - - - - Oliver Oberdorf oly@world.std.com - - - - Olof Johansson offe@ludd.luth.se - - - - Osokin Sergey aka oZZ ozz@FreeBSD.org.ru - - - - Pace Willisson pace@blitz.com - - - - Paco Rosich rosich@modico.eleinf.uv.es - - - - Palle Girgensohn girgen@partitur.se - - - - Parag Patel parag@cgt.com - - - - Pascal Pederiva pascal@zuo.dec.com - - - - Pasvorn Boonmark boonmark@juniper.net - - - - Patrick Gardella patrick@cre8tivegroup.com - - - - Patrick Hausen unknown - - - - Paul Antonov apg@demos.su - - - - Paul F. Werkowski unknown - - - - Paul Fox pgf@foxharp.boston.ma.us - - - - Paul Koch koch@thehub.com.au - - - - Paul Kranenburg pk@NetBSD.org - - - - Paul Mackerras paulus@cs.anu.edu.au - - - - Paul Popelka paulp@uts.amdahl.com - - - - Paul S. LaFollette, Jr. unknown - - - - Paul Saab paul@mu.org - - - - Paul Sandys myj@nyct.net - - - - Paul T. Root proot@horton.iaces.com - - - - Paul Vixie paul@vix.com - - - - Paulo Menezes paulo@isr.uc.pt - - - - Paulo Menezes pm@dee.uc.pt - - - - Pedro A M Vazquez vazquez@IQM.Unicamp.BR - - - - Pedro Giffuni giffunip@asme.org - - - - Pete Bentley pete@demon.net - - - - Peter Childs pjchilds@imforei.apana.org.au - - - - Peter Cornelius pc@inr.fzk.de - - - - Peter Haight peterh@prognet.com - - - - Peter Jeremy perer.jeremy@alcatel.com.au - - - - Peter M. Chen pmchen@eecs.umich.edu - - - - Peter Much peter@citylink.dinoex.sub.org - - - - Peter Olsson unknown - - - - Peter Philipp pjp@bsd-daemon.net - - - - Peter Stubbs PETERS@staidan.qld.edu.au - - - - Phil Maker pjm@cs.ntu.edu.au - - - - Phil Sutherland - philsuth@mycroft.dialix.oz.au - - - - Phil Taylor phil@zipmail.co.uk - - - - Philip Musumeci philip@rmit.edu.au - - - - Pierre Y. Dampure pierre.dampure@k2c.co.uk - - - - Pius Fischer pius@ienet.com - - - - Pomegranate daver@flag.blackened.net - - - - Powerdog Industries - kevin.ruddy@powerdog.com - - - - R. Kym Horsell - - - - Rajesh Vaidheeswarran rv@fore.com - - - - Ralf Friedl friedl@informatik.uni-kl.de - - - - Randal S. Masutani randal@comtest.com - - - - Randall Hopper rhh@ct.picker.com - - - - Randall W. Dean rwd@osf.org - - - - Randy Bush rbush@bainbridge.verio.net - - - - Reinier Bezuidenhout - rbezuide@mikom.csir.co.za - - - - Remy Card Remy.Card@masi.ibp.fr - - - - Ricardas Cepas rch@richard.eu.org - - - - Riccardo Veraldi veraldi@cs.unibo.it - - - - Richard Henderson richard@atheist.tamu.edu - - - - Richard Hwang rhwang@bigpanda.com - - - - Richard Kiss richard@homemail.com - - - - Richard J Kuhns rjk@watson.grauel.com - - - - Richard M. Neswold - rneswold@drmemory.fnal.gov - - - - Richard Seaman, Jr. dick@tar.com - - - - Richard Stallman rms@gnu.ai.mit.edu - - - - Richard Straka straka@user1.inficad.com - - - - Richard Tobin richard@cogsci.ed.ac.uk - - - - Richard Wackerbarth rkw@Dataplex.NET - - - - Richard Winkel rich@math.missouri.edu - - - - Richard Wiwatowski rjwiwat@adelaide.on.net - - - - Rick Macklem rick@snowhite.cis.uoguelph.ca - - - - Rick Macklin unknown - - - - Rob Austein sra@epilogue.com - - - - Rob Mallory rmallory@qualcomm.com - - - - Rob Snow rsnow@txdirect.net - - - - Robert Crowe bob@speakez.com - - - - Robert D. Thrush rd@phoenix.aii.com - - - - Robert Eckardt - roberte@MEP.Ruhr-Uni-Bochum.de - - - - Robert Sanders rsanders@mindspring.com - - - - Robert Sexton robert@kudra.com - - - - Robert Shady rls@id.net - - - - Robert Swindells swindellsr@genrad.co.uk - - - - Robert Watson robert@cyrus.watson.org - - - - Robert Withrow witr@rwwa.com - - - - Robert Yoder unknown - - - - Robin Carey - robin@mailgate.dtc.rankxerox.co.uk - - - - Roger Hardiman roger@cs.strath.ac.uk - - - - Roland Jesse jesse@cs.uni-magdeburg.de - - - - Ron Bickers rbickers@intercenter.net - - - - Ron Lenk rlenk@widget.xmission.com - - - - Ronald Kuehn kuehn@rz.tu-clausthal.de - - - - Rudolf Cejka unknown - - - - Ruslan Belkin rus@home2.UA.net - - - - Ruslan Ermilov ru@ucb.crimea.ua - - - - Ruslan Shevchenko rssh@cam.grad.kiev.ua - - - - Russell L. Carter rcarter@pinyon.org - - - - Russell Vincent rv@groa.uct.ac.za - - - - Ryan Younce ryany@pobox.com - - - - Ryuichiro IMURA imura@cs.titech.ac.jp - - - - SANETO Takanori sanewo@strg.sony.co.jp - - - - SAWADA Mizuki miz@qb3.so-net.ne.jp - - - - SUGIMURA Takashi sugimura@jp.FreeBSD.org - - - - SURANYI Peter - suranyip@jks.is.tsukuba.ac.jp - - - - Sakai Hiroaki sakai@miya.ee.kagu.sut.ac.jp - - - - Sakari Jalovaara sja@tekla.fi - - - - Sam Hartman hartmans@mit.edu - - - - Samuel Lam skl@ScalableNetwork.com - - - - Samuele Zannoli zannoli@cs.unibo.it - - - - Sander Vesik sander@haldjas.folklore.ee - - - - Sandro Sigala ssigala@globalnet.it - - - - Sascha Blank blank@fox.uni-trier.de - - - - Sascha Wildner swildner@channelz.GUN.de - - - - Satoh Junichi junichi@astec.co.jp - - - - Scot Elliott scot@poptart.org - - - - Scot W. Hetzel hetzels@westbend.net - - - - Scott A. Kenney saken@rmta.ml.org - - - - Scott Blachowicz - scott.blachowicz@seaslug.org - - - - Scott Burris scott@pita.cns.ucla.edu - - - - Scott Hazen Mueller scott@zorch.sf-bay.org - - - - Scott Michel scottm@cs.ucla.edu - - - - Scott Mitchel scott@uk.FreeBSD.org - - - - Scott Reynolds scott@clmqt.marquette.mi.us - - - - Sebastian Strollo seb@erix.ericsson.se - - - - Serge A. Babkin babkin@hq.icb.chel.su - - - - Serge V. Vakulenko vak@zebub.msk.su - - - - Sergei Chechetkin - csl@whale.sunbay.crimea.ua - - - - Sergei S. Laskavy laskavy@pc759.cs.msu.su - - - - Sergey Gershtein sg@mplik.ru - - - - Sergey Kosyakov ks@itp.ac.ru - - - - Sergey Potapov sp@alkor.ru - - - - Sergey Shkonda serg@bcs.zp.ua - - - - Sergey V.Dorokhov svd@kbtelecom.nalnet.ru - - - - Sergio Lenzi lenzi@bsi.com.br - - - - Shaun Courtney shaun@emma.eng.uct.ac.za - - - - Shawn M. Carey smcarey@mailbox.syr.edu - - - - Shigio Yamaguchi shigio@tamacom.com - - - - Shinya Esu esu@yk.rim.or.jp - - - - Shuichi Tanaka stanaka@bb.mbn.or.jp - - - - Shunsuke Akiyama akiyama@jp.FreeBSD.org - - - - Simon simon@masi.ibp.fr - - - - Simon Burge simonb@telstra.com.au - - - - Simon J Gerraty sjg@melb.bull.oz.au - - - - Simon Marlow simonm@dcs.gla.ac.uk - - - - Simon Shapiro shimon@simon-shapiro.org - - - - Sin'ichiro MIYATANI siu@phaseone.co.jp - - - - Slaven Rezic eserte@cs.tu-berlin.de - - - - Soochon Radee slr@mitre.org - - - - Soren Dayton csdayton@midway.uchicago.edu - - - - Soren Dossing sauber@netcom.com - - - - Soren S. Jorvang soren@dt.dk - - - - Stefan Bethke stb@hanse.de - - - - Stefan Eggers seggers@semyam.dinoco.de - - - - Stefan Moeding s.moeding@ndh.net - - - - Stefan Petri unknown - - - - Stefan `Sec` Zehl sec@42.org - - - - Steinar Haug sthaug@nethelp.no - - - - Stephane E. Potvin sepotvin@videotron.ca - - - - Stephane Legrand stephane@lituus.fr - - - - Stephen Clawson - sclawson@marker.cs.utah.edu - - - - Stephen F. Combs combssf@salem.ge.com - - - - Stephen Farrell stephen@farrell.org - - - - Stephen Hocking sysseh@devetir.qld.gov.au - - - - Stephen J. Roznowski sjr@home.net - - - - Stephen McKay syssgm@devetir.qld.gov.au - - - - Stephen Melvin melvin@zytek.com - - - - Steve Bauer sbauer@rock.sdsmt.edu - - - - Steve Coltrin spcoltri@io.com - - - - Steve Deering unknown - - - - Steve Gerakines steve2@genesis.tiac.net - - - - Steve Gericke steveg@comtrol.com - - - - Steve Piette steve@simon.chi.il.US - - - - Steve Schwarz schwarz@alpharel.com - - - - Steven G. Kargl - kargl@troutmask.apl.washington.edu - - - - Steven H. Samorodin samorodi@NUXI.com - - - - Steven McCanne mccanne@cs.berkeley.edu - - - - Steven Plite splite@purdue.edu - - - - Steven Wallace unknown - - - - Stuart Henderson - stuart@internationalschool.co.uk - - - - Sue Blake sue@welearn.com.au - - - - Sugimoto Sadahiro ixtl@komaba.utmc.or.jp - - - - Sugiura Shiro ssugiura@duo.co.jp - - - - Sujal Patel smpatel@wam.umd.edu - - - - Sune Stjerneby stjerneby@usa.net - - - - Suzuki Yoshiaki - zensyo@ann.tama.kawasaki.jp - - - - Tadashi Kumano kumano@strl.nhk.or.jp - - - - Taguchi Takeshi taguchi@tohoku.iij.ad.jp - - - - Takahiro Yugawa yugawa@orleans.rim.or.jp - - - - Takanori Watanabe - takawata@shidahara1.planet.sci.kobe-u.ac.jp - - - - Takashi Mega mega@minz.org - - - - Takashi Uozu j1594016@ed.kagu.sut.ac.jp - - - - Takayuki Ariga a00821@cc.hc.keio.ac.jp - - - - Takeru NAIKI naiki@bfd.es.hokudai.ac.jp - - - - Takeshi Amaike amaike@iri.co.jp - - - - Takeshi MUTOH mutoh@info.nara-k.ac.jp - - - - Takeshi Ohashi - ohashi@mickey.ai.kyutech.ac.jp - - - - Takeshi WATANABE - watanabe@crayon.earth.s.kobe-u.ac.jp - - - - Takuya SHIOZAKI - tshiozak@makino.ise.chuo-u.ac.jp - - - - Tatoku Ogaito tacha@tera.fukui-med.ac.jp - - - - Tatsumi HOSOKAWA hosokawa@jp.FreeBSD.org - - - - Ted Buswell tbuswell@mediaone.net - - - - Ted Faber faber@isi.edu - - - - Ted Lemon mellon@isc.org - - - - Terry Lambert terry@lambert.org - - - - Terry Lee terry@uivlsi.csl.uiuc.edu - - - - Tetsuya Furukawa tetsuya@secom-sis.co.jp - - - - Theo de Raadt deraadt@OpenBSD.org - - - - Thomas thomas@mathematik.uni-Bremen.de - - - - Thomas D. Dean tomdean@ix.netcom.com - - - - Thomas David Rivers rivers@dignus.com - - - - Thomas G. McWilliams tgm@netcom.com - - - - Thomas Gellekum - thomas@ghpc8.ihf.rwth-aachen.de - - - - Thomas Graichen - graichen@omega.physik.fu-berlin.de - - - - Thomas König - Thomas.Koenig@ciw.uni-karlsruhe.de - - - - Thomas Ptacek unknown - - - - Thomas A. Stephens tas@stephens.org - - - - Thomas Stromberg tstrombe@rtci.com - - - - Thomas Valentino Crimi - tcrimi+@andrew.cmu.edu - - - - Thomas Wintergerst thomas@lemur.nord.de - - - - Þórður Ívarsson - totii@est.is - - - - Tim Kientzle kientzle@netcom.com - - - - Tim Singletary - tsingle@sunland.gsfc.nasa.gov - - - - Tim Wilkinson tim@sarc.city.ac.uk - - - - Timo J. Rinne tri@iki.fi - - - - Todd Miller millert@openbsd.org - - - - Tom root@majestix.cmr.no - - - - Tom tom@sdf.com - - - - Tom Gray - DCA dcasba@rain.org - - - - Tom Jobbins tom@tom.tj - - - - Tom Pusateri pusateri@juniper.net - - - - Tom Rush tarush@mindspring.com - - - - Tom Samplonius tom@misery.sdf.com - - - - Tomohiko Kurahashi - kura@melchior.q.t.u-tokyo.ac.jp - - - - Tony Kimball alk@Think.COM - - - - Tony Li tli@jnx.com - - - - Tony Lynn wing@cc.nsysu.edu.tw - - - - Tony Maher tonym@angis.org.au - - - - Torbjorn Granlund tege@matematik.su.se - - - - Toshihiko ARAI toshi@tenchi.ne.jp - - - - Toshihiko SHIMOKAWA toshi@tea.forus.or.jp - - - - Toshihiro Kanda candy@kgc.co.jp - - - - Toshiomi Moriki - Toshiomi.Moriki@ma1.seikyou.ne.jp - - - - Trefor S. trefor@flevel.co.uk - - - - Trevor Blackwell tlb@viaweb.com - - - - URATA Shuichiro s-urata@nmit.tmg.nec.co.jp - - - - Udo Schweigert ust@cert.siemens.de - - - - Ugo Paternostro paterno@dsi.unifi.it - - - - Ulf Kieber kieber@sax.de - - - - Ulli Linzen ulli@perceval.camelot.de - - - - Ustimenko Semen semen@iclub.nsu.ru - - - - Uwe Arndt arndt@mailhost.uni-koblenz.de - - - - Vadim Chekan vadim@gc.lviv.ua - - - - Vadim Kolontsov vadim@tversu.ac.ru - - - - Vadim Mikhailov mvp@braz.ru - - - - Van Jacobson van@ee.lbl.gov - - - - Vasily V. Grechishnikov - bazilio@ns1.ied-vorstu.ac.ru - - - - Vasim Valejev vasim@uddias.diaspro.com - - - - Vernon J. Schryver vjs@mica.denver.sgi.com - - - - Vic Abell abe@cc.purdue.edu - - - - Ville Eerola ve@sci.fi - - - - Vincent Poy vince@venus.gaianet.net - - - - Vincenzo Capuano - VCAPUANO@vmprofs.esoc.esa.de - - - - Virgil Champlin champlin@pa.dec.com - - - - Vladimir A. Jakovenko - vovik@ntu-kpi.kiev.ua - - - - Vladimir Kushnir kushn@mail.kar.net - - - - Vsevolod Lobko seva@alex-ua.com - - - - W. Gerald Hicks wghicks@bellsouth.net - - - - W. Richard Stevens rstevens@noao.edu - - - - Walt Howard howard@ee.utah.edu - - - - Warren Toomey wkt@csadfa.cs.adfa.oz.au - - - - Wayne Scott wscott@ichips.intel.com - - - - Werner Griessl - werner@btp1da.phy.uni-bayreuth.de - - - - Wes Santee wsantee@wsantee.oz.net - - - - Wietse Venema wietse@wzv.win.tue.nl - - - - Wilfredo Sanchez wsanchez@apple.com - - - - Wiljo Heinen wiljo@freeside.ki.open.de - - - - Wilko Bulte wilko@yedi.iaf.nl - - - - Will Andrews andrews@technologist.com - - - - Willem Jan Withagen wjw@surf.IAE.nl - - - - William Jolitz withheld - - - - William Liao william@tale.net - - - - Wojtek Pilorz - wpilorz@celebris.bdk.lublin.pl - - - - Wolfgang Helbig helbig@ba-stuttgart.de - - - - Wolfgang Solfrank ws@tools.de - - - - Wolfgang Stanglmeier wolf@FreeBSD.org - - - - Wu Ching-hong woju@FreeBSD.ee.Ntu.edu.TW - - - - Yarema yds@ingress.com - - - - Yaroslav Terletsky ts@polynet.lviv.ua - - - - Yasuhito FUTATSUKI futatuki@fureai.or.jp - - - - Yasuhiro Fukama yasuf@big.or.jp - - - - Yen-Shuo Su yssu@CCCA.NCTU.edu.tw - - - - Ying-Chieh Liao ijliao@csie.NCTU.edu.tw - - - - Yixin Jin yjin@rain.cs.ucla.edu - - - - Yoshiaki Uchikawa yoshiaki@kt.rim.or.jp - - - - Yoshihiko OHTA yohta@bres.tsukuba.ac.jp - - - - Yoshihisa NAKAGAWA - y-nakaga@ccs.mt.nec.co.jp - - - - Yoshikazu Goto gotoh@ae.anritsu.co.jp - - - - Yoshimasa Ohnishi - ohnishi@isc.kyutech.ac.jp - - - - Yoshishige Arai ryo2@on.rim.or.jp - - - - Yuichi MATSUTAKA matutaka@osa.att.ne.jp - - - - Yujiro MIYATA - miyata@bioele.nuee.nagoya-u.ac.jp - - - - Yukihiro Nakai nacai@iname.com - - - - Yusuke Nawano azuki@azkey.org - - - - Yuu Yashiki s974123@cc.matsuyama-u.ac.jp - - - - Yuval Yarom yval@cs.huji.ac.il - - - - Yves Fonk yves@cpcoup5.tn.tudelft.nl - - - - Yves Fonk yves@dutncp8.tn.tudelft.nl - - - - Zach Heilig zach@gaffaneys.com - - - - Zahemszhky Gabor zgabor@code.hu - - - - Zhong Ming-Xun zmx@mail.CDPA.nsysu.edu.tw - - - - arci vega@sophia.inria.fr - - - - der Mouse mouse@Collatz.McRCIM.McGill.EDU - - - - frf frf@xocolatl.com - - - - Ege Rekk aagero@aage.priv.no - - - - - - 386BSD Patch Kit Patch Contributors - - (in alphabetical order by first name): - - - - Adam Glass glass@postgres.berkeley.edu - - - - Adrian Hall adrian@ibmpcug.co.uk - - - - Andrey A. Chernov ache@astral.msk.su - - - - Andrew Herbert andrew@werple.apana.org.au - - - - Andrew Moore alm@netcom.com - - - - Andy Valencia ajv@csd.mot.com - jtk@netcom.com - - - - Arne Henrik Juul arnej@Lise.Unit.NO - - - - Bakul Shah bvs@bitblocks.com - - - - Barry Lustig barry@ictv.com - - - - Bob Wilcox bob@obiwan.uucp - - - - Branko Lankester - - - - Brett Lymn blymn@mulga.awadi.com.AU - - - - Charles Hannum mycroft@ai.mit.edu - - - - Chris G. Demetriou - cgd@postgres.berkeley.edu - - - - Chris Torek torek@ee.lbl.gov - - - - Christoph Robitschko - chmr@edvz.tu-graz.ac.at - - - - Daniel Poirot poirot@aio.jsc.nasa.gov - - - - Dave Burgess burgess@hrd769.brooks.af.mil - - - - Dave Rivers rivers@ponds.uucp - - - - David Dawes dawes@physics.su.OZ.AU - - - - David Greenman dg@Root.COM - - - - Eric J. Haug ejh@slustl.slu.edu - - - - Felix Gaehtgens - felix@escape.vsse.in-berlin.de - - - - Frank Maclachlan fpm@crash.cts.com - - - - Gary A. Browning gab10@griffcd.amdahl.com - - - - Gary Howland gary@hotlava.com - - - - Geoff Rehmet csgr@alpha.ru.ac.za - - - - Goran Hammarback goran@astro.uu.se - - - - Guido van Rooij guido@gvr.org - - - - Guy Harris guy@auspex.com - - - - Havard Eidnes - Havard.Eidnes@runit.sintef.no - - - - Herb Peyerl hpeyerl@novatel.cuc.ab.ca - - - - Holger Veit Holger.Veit@gmd.de - - - - Ishii Masahiro, R. Kym Horsell - - - - J.T. Conklin jtc@cygnus.com - - - - Jagane D Sundar jagane@netcom.com - - - - James Clark jjc@jclark.com - - - - James Jegers jimj@miller.cs.uwm.edu - - - - James W. Dolter - - - - James da Silva jds@cs.umd.edu et al - - - - Jay Fenlason hack@datacube.com - - - - Jim Wilson wilson@moria.cygnus.com - - - - Jörg Lohse - lohse@tech7.informatik.uni-hamburg.de - - - - Jörg Wunsch - joerg_wunsch@uriah.heep.sax.de - - - - John Dyson - - - - John Woods jfw@eddie.mit.edu - - - - Jordan K. Hubbard jkh@whisker.hubbard.ie - - - - Julian Elischer julian@dialix.oz.au - - - - Julian Stacey jhs@FreeBSD.org - - - - Karl Dietz Karl.Dietz@triplan.com - - - - Karl Lehenbauer karl@NeoSoft.com - karl@one.neosoft.com - - - - Keith Bostic bostic@toe.CS.Berkeley.EDU - - - - Ken Hughes - - - - Kent Talarico kent@shipwreck.tsoft.net - - - - Kevin Lahey kml%rokkaku.UUCP@mathcs.emory.edu - kml@mosquito.cis.ufl.edu - - - - Marc Frajola marc@dev.com - - - - Mark Tinguely tinguely@plains.nodak.edu - tinguely@hookie.cs.ndsu.NoDak.edu - - - - Martin Renters martin@tdc.on.ca - - - - Michael Clay mclay@weareb.org - - - - Michael Galassi nerd@percival.rain.com - - - - Mike Durkin mdurkin@tsoft.sf-bay.org - - - - Naoki Hamada nao@tom-yam.or.jp - - - - Nate Williams nate@bsd.coe.montana.edu - - - - Nick Handel nhandel@NeoSoft.com - nick@madhouse.neosoft.com - - - - Pace Willisson pace@blitz.com - - - - Paul Kranenburg pk@cs.few.eur.nl - - - - Paul Mackerras paulus@cs.anu.edu.au - - - - Paul Popelka paulp@uts.amdahl.com - - - - Peter da Silva peter@NeoSoft.com - - - - Phil Sutherland - philsuth@mycroft.dialix.oz.au - - - - Poul-Henning Kampphk@FreeBSD.org - - - - Ralf Friedl friedl@informatik.uni-kl.de - - - - Rick Macklem root@snowhite.cis.uoguelph.ca - - - - Robert D. Thrush rd@phoenix.aii.com - - - - Rodney W. Grimes rgrimes@cdrom.com - - - - Sascha Wildner swildner@channelz.GUN.de - - - - Scott Burris scott@pita.cns.ucla.edu - - - - Scott Reynolds scott@clmqt.marquette.mi.us - - - - Sean Eric Fagan sef@kithrup.com - - - - Simon J Gerraty sjg@melb.bull.oz.au - sjg@zen.void.oz.au - - - - Stephen McKay syssgm@devetir.qld.gov.au - - - - Terry Lambert terry@icarus.weber.edu - - - - Terry Lee terry@uivlsi.csl.uiuc.edu - - - - Tor Egge Tor.Egge@idi.ntnu.no - - - - Warren Toomey wkt@csadfa.cs.adfa.oz.au - - - - Wiljo Heinen wiljo@freeside.ki.open.de - - - - William Jolitz withheld - - - - Wolfgang Solfrank ws@tools.de - - - - Wolfgang Stanglmeier wolf@dentaro.GUN.de - - - - Yuval Yarom yval@cs.huji.ac.il - - - - - - - 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 Cutting Edge: FreeBSD-current and FreeBSD-stable - - 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. - - - Staying Current with FreeBSD - - Contributed by &a.jkh;. - - - What is FreeBSD-current? - - 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! - - - - Who needs FreeBSD-current? - - FreeBSD-current is made generally available for 3 primary interest - groups: - - - - 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. - - - - 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. - - - - 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 reading, not - running). These people also make the occasional comment or - contribute code. - - - - - - What is FreeBSD-current <emphasis>not</emphasis>? - - - - 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. - - - - A quick way of getting bug fixes. - - - - 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 - do not have the time 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 and 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. - - - - - - Using FreeBSD-current - - - - Join the &a.current; and the &a.cvsall; . This is not just a - good idea, it is essential. If you are not - on the FreeBSD-current 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. - - The cvs-all 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. - - To join these lists, send mail to - &a.majordomo; and specify: - - -subscribe freebsd-current -subscribe cvs-all - - in the body of your message. Optionally, you can also say - help and Majordomo will send you full help on - how to subscribe and unsubscribe to the various other mailing - lists we support. - - - - Grab the sources from ftp.FreeBSD.org. You can do this in three - ways: - - - - Use the CTM facility. Unless - you have a good TCP/IP connection at a flat rate, this is - the way to do it. - - - - Use the cvsup program with - this - supfile. 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: - -
&prompt.root; pkg_add -f \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz
- - - - Use ftp. The source tree for - FreeBSD-current is always “exported” on: ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current. - We also use wu-ftpd which allows - compressed/tar'd grabbing of whole trees. e.g. you - see: - - usr.bin/lex - - You can do: - - ftp> cd usr.bin -ftp> get lex.tar.Z - - and it will get the whole directory for you as a compressed - tar file. - - - - - - Essentially, if you need rapid on-demand access to the source - and communications bandwidth is not a consideration, use - cvsup or ftp. Otherwise, - use CTM. - - If you are grabbing the sources to run, and not just look at, - then grab all 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. - - Before compiling current, read the Makefile in - /usr/src carefully. You should at least run - a make world 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. - - - - 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! - - - - - - - Staying Stable with FreeBSD - - Contributed by &a.jkh;. - - - What is FreeBSD-stable? - - 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 FreeBSD-current). - - - - Who needs FreeBSD-stable? - - If you are a commercial user or someone who puts maximum stability - of their FreeBSD system before all other concerns, you should consider - tracking stable. This is especially true if you - have installed the most recent release (&rel.current;-RELEASE - at the time of this writing) since the stable - branch is effectively a bug-fix stream relative to the previous - release. - - - The stable 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 current before - bringing them into stable, but sometimes our - tests fail to catch every case. If something breaks for you in - stable, please let us know - immediately! (see next section). - - - - - Using FreeBSD-stable - - - - - Join the &a.stable;. This will keep you informed of - build-dependencies that may appear in stable - 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. - - The cvs-all 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. - - To join these lists, send mail to &a.majordomo; and specify: - - -subscribe freebsd-stable -subscribe cvs-all - - in the body of your message. Optionally, you can also say - help and Majordomo will send you full help on - how to subscribe and unsubscribe to the various other mailing - lists we support. - - - - 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 ftp://releng3.FreeBSD.org/pub/FreeBSD/ - and install it like any other release. - - If you are already running a previous release of 2.2 and wish - to upgrade via sources then you can easily do so from ftp.FreeBSD.org. This can be done in one - of three ways: - - - - Use the CTM facility. Unless - you have a good TCP/IP connection at a flat rate, this is - the way to do it. - - - - Use the cvsup program with - this - supfile. 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; - -
&prompt.root; pkg_add -f \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz
- - - - Use ftp. The source tree for - FreeBSD-stable is always “exported” on: ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable - - We also use wu-ftpd which allows - compressed/tar'd grabbing of whole trees. e.g. you - see: - - usr.bin/lex - - You can do: - - ftp> cd usr.bin -ftp> get lex.tar.Z - - and it will get the whole directory for you as a compressed - tar file. - - - - - - Essentially, if you need rapid on-demand access to the source - and communications bandwidth is not a consideration, use - cvsup or ftp. Otherwise, - use CTM. - - - - Before compiling stable, read the Makefile in - /usr/src carefully. You should at least run - a make world 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. - - - - - - - Synchronizing Source Trees over the Internet - - Contributed by &a.jkh;. - - 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 Anonymous CVS, CVSup, and CTM. - - Anonymous CVS and - CVSup use the pull model - of updating sources. In the case of CVSup - the user (or a cron script) invokes the cvsup - program, and it interacts with a cvsupd 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. - Anonymous CVS is quite a bit more simplistic - than CVSup in that it's just an extension to - CVS which allows it to pull changes directly - from a remote CVS repository. CVSup can do - this far more efficiently, but Anonymous CVS - is easier to use. - - CTM, 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 CVSup, and - places less strain on our server resources since it is a - push rather than a pull - model. - - There are other trade-offs, of course. If you inadvertently wipe - out portions of your archive, CVSup will - detect and rebuild the damaged portions for you. - CTM 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. - - For more information on Anonymous CVS, - CTM, and CVSup, - please see one of the following sections: - - - Anonymous CVS - - Contributed by &a.jkh; - - - <anchor id="anoncvs-intro">Introduction - - Anonymous CVS (or, as it is otherwise known, - anoncvs) 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 CVSROOT environment - variable to point at the appropriate anoncvs server and then uses - the &man.cvs.1; command to access it like any local - repository. - - While it can also be said that the CVSup and anoncvs - 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, - CVSup 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 - CVSup, a special client must first be - installed and configured before any bits can be grabbed, and then - only in the fairly large chunks which - CVSup calls - collections. - - Anoncvs, by contrast, can be used to - examine anything from an individual file to a specific program (like - ls or grep) by referencing the - CVS module name. Of course, anoncvs 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 - CVSup is really your only option. - - - - <anchor id="anoncvs-usage">Using Anonymous CVS - - Configuring &man.cvs.1; to use an Anonymous CVS repository is a - simple matter of setting the CVSROOT environment - variable to point to one of the FreeBSD project's - anoncvs servers. At the time of this writing, - the following servers are available: - - - - USA: - anoncvs@anoncvs.FreeBSD.org:/cvs - - - - Since CVS allows one to “check out” virtually any - version of the FreeBSD sources that ever existed (or, in some cases, - will exist :), you need to be familiar with the - revision () flag to &man.cvs.1; and what some of - the permissible values for it in the FreeBSD Project repository - are. - - 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. - - Here are the branch tags that users might be interested - in: - - - - HEAD - - - Symbolic name for the main line, or FreeBSD-current. Also - the default when no revision is specified. - - - - - RELENG_3 - - - The line of development for FreeBSD-3.x, also known as - FreeBSD-stable. Not valid for the ports collection. - - - - - RELENG_2_2 - - - 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. - - - - - RELENG_2_1_0 - - - The line of development for FreeBSD-2.1.x - this branch is - largely obsolete. Not valid for the ports collection. - - - - - Here are the revision tags that users might be interested - in: - - - - - RELENG_3_2_0_RELEASE - - - FreeBSD-3.2. Not valid for the ports collection. - - - - - - RELENG_3_1_0_RELEASE - - - FreeBSD-3.1. Not valid for the ports collection. - - - - - RELENG_3_0_0_RELEASE - - - FreeBSD-3.0. Not valid for the ports collection. - - - - - RELENG_2_2_8_RELEASE - - - FreeBSD-2.2.8. Not valid for the ports collection. - - - - - RELENG_2_2_7_RELEASE - - - FreeBSD-2.2.7. Not valid for the ports collection. - - - - - RELENG_2_2_6_RELEASE - - - FreeBSD-2.2.6. Not valid for the ports collection. - - - - - RELENG_2_2_5_RELEASE - - - FreeBSD-2.2.5. Not valid for the ports collection. - - - - - RELENG_2_2_2_RELEASE - - - FreeBSD-2.2.2. Not valid for the ports collection. - - - - - RELENG_2_2_1_RELEASE - - - FreeBSD-2.2.1. Not valid for the ports collection. - - - - - RELENG_2_2_0_RELEASE - - - FreeBSD-2.2.0. Not valid for the ports collection. - - - - - RELENG_2_1_7_RELEASE - - - FreeBSD-2.1.7. Not valid for the ports collection. - - - - - RELENG_2_1_6_1_RELEASE - - - FreeBSD-2.1.6.1. Not valid for the ports - collection. - - - - - RELENG_2_1_6_RELEASE - - - FreeBSD-2.1.6. Not valid for the ports collection. - - - - - RELENG_2_1_5_RELEASE - - - FreeBSD-2.1.5. Not valid for the ports collection. - - - - - RELENG_2_1_0_RELEASE - - - FreeBSD-2.1.0. Not valid for the ports collection. - - - - - 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 flag. See the &man.cvs.1; man page - for more details. - - - - Examples - - 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: - - - Checking out something from -current (&man.ls.1;) and - deleting it again: - - -&prompt.user; setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs -&prompt.user; cvs co ls -&prompt.user; cvs release -d ls - - - - Checking out the version of ls(1) in the 2.2-stable - branch: - - -&prompt.user; setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs -&prompt.user; cvs co -rRELENG_2_2 ls -&prompt.user; cvs release -d ls - - - - Creating a list of changes (as unidiffs) to &man.ls.1; - - -&prompt.user; setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs -&prompt.user; cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls - - - - Finding out what other module names can be used: - - -&prompt.user; setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs -&prompt.user; cvs co modules -&prompt.user; more modules/modules -&prompt.user; cvs release -d modules - - - - - Other Resources - - The following additional resources may be helpful in learning - CVS: - - - - CVS Tutorial from Cal Poly. - - - - Cyclic Software, - commercial maintainers of CVS. - - - - CVSWeb is - the FreeBSD Project web interface for CVS. - - - - - - - <application>CTM</application> - - Contributed by &a.phk;. Updated - 19-October-1997. - - CTM 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 - CTM for other things. - - - Why should I use <application>CTM</application>? - - CTM 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, CTM 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, - CTM 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. - - 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 - Staying current with FreeBSD. - - - - What do I need to use <application>CTM</application>? - - You will need two things: The CTM - program and the initial deltas to feed it (to get up to - “current” levels). - - The CTM program has been part of - FreeBSD ever since version 2.0 was released, and lives in - /usr/src/usr.sbin/CTM if you have a copy of the - source online. - - If you are running a pre-2.0 version of FreeBSD, you can fetch - the current CTM sources directly - from: - - ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm - - The “deltas” you feed CTM - 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 - CTM: - - ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM - - or see section mirrors. - - FTP the relevant directory and fetch the - README file, starting from there. - - If you may wish to get your deltas via email: - - Send email to &a.majordomo; to subscribe to one of the - CTM 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 help - — it will send you back usage instructions.) - - When you begin receiving your CTM - updates in the mail, you may use the ctm_rmail - program to unpack and apply them. You can actually use the - ctm_rmail program directly from a entry in - /etc/aliases if you want to have the process - run in a fully automated fashion. Check the - ctm_rmail man page for more details. - - - No matter what method you use to get the - CTM deltas, you should subscribe to the - ctm-announce@FreeBSD.org mailing list. In the - future, this will be the only place where announcements concerning - the operations of the CTM system will - be posted. Send an email to &a.majordomo; with a single line of - subscribe ctm-announce to get added to the - list. - - - - - Starting off with <application>CTM</application> for the first - time - - Before you can start using CTM - deltas, you will need to get to a starting point for the deltas - produced subsequently to it. - - 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 - CTM 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. - - 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. - - You can recognize these “starter” deltas by the - X appended to the number - (src-cur.3210XEmpty.gz for instance). The - designation following the X corresponds to the - origin of your initial “seed”. - Empty is an empty directory. As a rule a base - transition from Empty is produced every 100 - deltas. By the way, they are large! 25 to 30 Megabytes of - gzip'ed data is common for the - XEmpty deltas. - - Once you've picked a base delta to start from, you will also - need all deltas with higher numbers following it. - - - - Using <application>CTM</application> in your daily life - - To apply the deltas, simply say: - - &prompt.root; cd /where/ever/you/want/the/stuff -&prompt.root; ctm -v -v /where/you/store/your/deltas/src-xxx.* - - CTM understands deltas which have - been put through gzip, so you do not need to - gunzip them first, this saves disk space. - - Unless it feels very secure about the entire process, - CTM will not touch your tree. To verify - a delta you can also use the flag and - CTM 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. - - There are other options to CTM as - well, see the manual pages or look in the sources for more - information. - - 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... - - That's really all there is to it. Every time you get a new - delta, just run it through CTM to keep - your sources up to date. - - 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 - fdwrite to make a copy. - - - - Keeping your local changes - - As a developer one would like to experiment with and change - files in the source tree. CTM supports - local modifications in a limited way: before checking for the - presence of a file foo, it first looks for - foo.ctm. If this file exists, CTM will operate - on it instead of foo. - - 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 .ctm suffix. Then you can freely - hack the code, while CTM keeps the .ctm file - up-to-date. - - - - Other interesting <application>CTM</application> options - - - Finding out exactly what would be touched by an - update - - You can determine the list of changes that - CTM will make on your source repository - using the option to - CTM. - - 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 :-). - - - - Making backups before updating - - Sometimes you may want to backup all the files that would be - changed by a CTM update. - - Specifying the option causes - CTM to backup all files that would be - touched by a given CTM delta to - backup-file. - - - - Restricting the files touched by an update - - Sometimes you would be interested in restricting the scope of - a given CTM update, or may be - interested in extracting just a few files from a sequence of - deltas. - - You can control the list of files that - CTM would operate on by specifying - filtering regular expressions using the and - options. - - For example, to extract an up-to-date copy of - lib/libc/Makefile from your collection of - saved CTM deltas, run the commands: - - &prompt.root; cd /where/ever/you/want/to/extract/it/ -&prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.* - - For every file specified in a CTM - delta, the and options are - applied in the order given on the command line. The file is - processed by CTM only if it is marked - as eligible after all the and - options are applied to it. - - - - - Future plans for <application>CTM</application> - - Tons of them: - - - - Use some kind of authentication into the CTM system, so as - to allow detection of spoofed CTM updates. - - - - Clean up the options to CTM, they - became confusing and counter intuitive. - - - - 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... - - - - Miscellaneous stuff - - 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 sec-cur sequence too. - There is a sequence of deltas for the ports - 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. - - - - Thanks! - - - - &a.bde; - - - for his pointed pen and invaluable comments. - - - - - &a.sos; - - - for patience. - - - - - Stephen McKay - - - wrote ctm_[rs]mail, much - appreciated. - - - - - &a.jkh; - - - for being so stubborn that I had to make it better. - - - - - All the users - - - I hope you like it... - - - - - - - - <application>CVSup</application> - - Contributed by &a.jdp;. - - - Introduction - - CVSup 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 - CVSup, FreeBSD users can easily keep - their own source trees up to date. - - CVSup uses the so-called - pull 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 - CVSup client manually to get an update, - or they must set up a cron job to run it - automatically on a regular basis. - - The term CVSup, capitalized just so, - refers to the entire software package. Its main components are the - client cvsup which runs on each user's machine, - and the server cvsupd which runs at each of the - FreeBSD mirror sites. - - As you read the FreeBSD documentation and mailing lists, you may - see references to sup. - Sup was the predecessor of - CVSup, and it served a similar purpose. - CVSup is in used in much the same way as - sup and, in fact, uses configuration files which are - backward-compatible with sup's. - Sup is no longer used in the FreeBSD - project, because CVSup is both faster and - more flexible. - - - - Installation - - The easiest way to install CVSup if - you are running FreeBSD 2.2 or later is to use either the - port from the FreeBSD ports - collection or the corresponding binary - package, depending on whether you prefer to roll your own - or not. - - 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 the - port, however, just as with FreeBSD 2.2. Simply unpack - the tar file, cd to the cvsup subdirectory and type make - install. - - Because CVSup is written in Modula-3, - both the package and the port require that the Modula-3 runtime - libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 package. - If you follow the same directions as for cvsup, - these libraries will be compiled and/or installed automatically when - you install the CVSup port or - package. - - 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 statically - linked FreeBSD executables for - CVSup from the USA distribution - site: - - - - ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup-bin-16.0.tar.gz (client including GUI). - - - - ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-16.0.tar.gz (client without GUI). - - - - ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupd-bin-16.0.tar.gz (server). - - - - as well as from the many FreeBSD FTP - mirror sites around the world. - - 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. - - In summary, your options for installing CVSup are: - - - - FreeBSD-2.2 or later: static binary, port, or - package - - - - FreeBSD-2.1.6, 2.1.7: static binary or port - - - - FreeBSD-2.1.5 or earlier: static binary - - - - - - CVSup Configuration - - CVSup's operation is controlled by a - configuration file called the supfile. - Beginning with FreeBSD-2.2, there are some sample - supfiles in the directory /usr/share/examples/cvsup. - These examples are also available from ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/ if you are on a pre-2.2 system. - - The information in a supfile answers the - following questions for cvsup: - - - - Which files do you want - to receive? - - - - Which versions of them do - you want? - - - - Where do you want to get - them from? - - - - Where do you want to put - them on your own machine? - - - - Where do you want to put - your status files? - - - - In the following sections, we will construct a typical - supfile by answering each of these questions in - turn. First, we describe the overall structure of a - supfile. - - A supfile is a text file. Comments begin - with # and extend to the end of the line. Lines - that are blank and lines that contain only comments are - ignored. - - 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., - delete or compress. A value - field also begins with a keyword, but the keyword is followed - without intervening white space by = and a second - word. For example, release=cvs is a value - field. - - A supfile typically specifies more than one - collection to receive. One way to structure a - supfile is to specify all of the relevant - fields explicitly for each collection. However, that tends to make - the supfile lines quite long, and it is - inconvenient because most fields are the same for all of the - collections in a supfile. - CVSup provides a defaulting mechanism to - avoid these problems. Lines beginning with the special - pseudo-collection name *default can be used to - set flags and values which will be used as defaults for the - subsequent collections in the supfile. 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 - *default lines. - - With this background, we will now proceed to construct a - supfile for receiving and updating the main - source tree of FreeBSD-current. - - - - Which files do you want to receive? - - The files available via CVSup are - organized into named groups called “collections”. - The collections that are available are described here. In this example, we wish - to receive the entire main source tree for the FreeBSD system. - There is a single large collection src-all - 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, cvs-crypto. - As a first step toward constructing our - supfile, we simply list these collections, - one per line: - - -src-all -cvs-crypto - - - - Which version(s) of them do you want? - - With CVSup, 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 tag= and - value fields. - - - Be very careful to specify any tag= - 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 only - tag=. for the - ports-* collections. - - - The tag= 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. - - Here are the branch tags that users might be interested - in: - - - - tag=. - - - The main line of development, also known as - FreeBSD-current. - - - The . is not punctuation; it is - the name of the tag. Valid for all collections. - - - - - - RELENG_3 - - - The line of development for FreeBSD-3.x, also known as - FreeBSD-stable. Not valid for the ports - collection. - - - - - RELENG_2_2 - - - The line of development for FreeBSD-2.2.x, also known - as 2.2-stable. Not valid for the ports collection. - - - - - tag=RELENG_2_1_0 - - - The line of development for FreeBSD-2.1.x - this - branch is largely obsolete. Not valid for the ports-* - collections. - - - - - Here are the revision tags that users might be interested - in: - - - - - tag=RELENG_3_2_0_RELEASE - - - FreeBSD-3.2. Not valid for the ports-* - collections. - - - - - tag=RELENG_3_1_0_RELEASE - - - FreeBSD-3.1. Not valid for the ports-* - collections. - - - - - tag=RELENG_3_0_0_RELEASE - - - FreeBSD-3.0. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_2_8_RELEASE - - - FreeBSD-2.2.8. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_2_7_RELEASE - - - FreeBSD-2.2.7. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_2_6_RELEASE - - - FreeBSD-2.2.6. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_2_5_RELEASE - - - FreeBSD-2.2.5. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_2_2_RELEASE - - - FreeBSD-2.2.2. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_2_1_RELEASE - - - FreeBSD-2.2.1. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_2_0_RELEASE - - - FreeBSD-2.2.0. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_1_7_RELEASE - - - FreeBSD-2.1.7. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_1_6_1_RELEASE - - - FreeBSD-2.1.6.1. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_1_6_RELEASE - - - FreeBSD-2.1.6. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_1_5_RELEASE - - - FreeBSD-2.1.5. Not valid for the ports-* - collections. - - - - - tag=RELENG_2_1_0_RELEASE - - - FreeBSD-2.1.0. Not valid for the ports-* - collections. - - - - - - Be very careful to type the tag name exactly as shown. - CVSup cannot distinguish between - valid and invalid tags. If you misspell the tag, - CVSup 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. - - - 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 value field. - The &man.cvsup.1; manual page explains how to do - that. - - For our example, we wish to receive FreeBSD-current. We add - this line at the beginning of our - supfile: - - -*default tag=. - - There is an important special case that comes into play if - you specify neither a tag= field nor a - date= 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. - - - - Where do you want to get them from? - - We use the host= field to tell - cvsup where to obtain its updates. Any of - the CVSup mirror sites 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, cvsup666.FreeBSD.org: - - -*default host=cvsup666.FreeBSD.org - - You will need to change the host to one that actually exists - before running CVSup. On any particular run of - cvsup, you can override the host setting on - the command line, with . - - - - Where do you want to put them on your own machine? - - The prefix= field tells - cvsup where to put the files it receives. In - this example, we will put the source files directly into our - main source tree, /usr/src. The - src directory is already implicit in the - collections we have chosen to receive, so this is the correct - specification: - - -*default prefix=/usr - - - - Where should cvsup maintain its status - files? - - The cvsup client maintains certain status files in what is - called the “base” directory. These files help - CVSup to work more efficiently, by - keeping track of which updates you have already received. We - will use the standard base directory, - /usr/local/etc/cvsup: - - -*default base=/usr/local/etc/cvsup - - This setting is used by default if it is not specified in - the supfile, so we actually do not need the - above line. - - If your base directory does not already exist, now would be - a good time to create it. The cvsup client - will refuse to run if the base directory does not exist. - - - - Miscellaneous supfile settings: - - There is one more line of boiler plate that normally needs - to be present in the supfile: - - -*default release=cvs delete use-rel-suffix compress - - release=cvs 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. - - delete gives - CVSup permission to delete files. - You should always specify this, so that - CVSup can keep your source tree fully - up to date. CVSup is careful to - delete only those files for which it is responsible. Any extra - files you happen to have will be left strictly alone. - - use-rel-suffix 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. - - compress 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. - - - - Putting it all together: - - Here is the entire supfile for our - example: - - -*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 - - - - - - Running <application>CVSup</application> - - You are now ready to try an update. The command line for doing - this is quite simple: - - &prompt.root; cvsup supfile - - where supfile is - of course the name of the supfile you have just created. Assuming - you are running under X11, cvsup will display a - GUI window with some buttons to do the usual things. Press the - “go” button, and watch it run. - - Since you are updating your actual /usr/src - tree in this example, you will need to run the program as - root so that cvsup 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: - - &prompt.root; mkdir /var/tmp/dest -&prompt.root; cvsup supfile /var/tmp/dest - - The directory you specify will be used as the destination - directory for all file updates. CVSup - will examine your usual files in /usr/src, but - it will not modify or delete any of them. Any file updates will - instead land in /var/tmp/dest/usr/src. - CVSup 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 /usr/src, you do not even - need to be root to perform this kind of trial run. - - 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: - - &prompt.root; cvsup -g -L 2 supfile - - The tells cvsup not to use its GUI. This is - automatic if you are not running X11, but otherwise you have to - specify it. - - The tells cvsup to print out the details - of all the file updates it is doing. There are three levels of - verbosity, from to . The - default is 0, which means total silence except for error - messages. - - There are plenty of other options available. For a brief list - of them, type cvsup -H. For more detailed - descriptions, see the manual page. - - 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. - - - - <application>CVSup</application> File Collections - - The file collections available via - CVSup 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. - - The most commonly used collections are - src-all, cvs-crypto, and - ports-all. The other collections are used only - by small groups of people for specialized purposes, and some mirror - sites may not carry all of them. - - - - cvs-all release=cvs - - - The main FreeBSD CVS repository, excluding the - export-restricted cryptography code. - - - - distrib release=cvs - - - Files related to the distribution and mirroring of - FreeBSD. - - - - - doc-all release=cvs - - - Sources for the FreeBSD handbook and other - documentation. - - - - - ports-all release=cvs - - - The FreeBSD ports collection. - - - - ports-archivers - release=cvs - - - Archiving tools. - - - - - ports-astro - release=cvs - - - Astronomical ports. - - - - - ports-audio - release=cvs - - - Sound support. - - - - - ports-base release=cvs - - - Miscellaneous files at the top of - /usr/ports. - - - - - ports-benchmarks - release=cvs - - - Benchmarks. - - - - - ports-biology - release=cvs - - - Biology. - - - - - ports-cad release=cvs - - - Computer aided design tools. - - - - - ports-chinese - release=cvs - - - Chinese language support. - - - - - ports-comms - release=cvs - - - Communication software. - - - - - ports-converters - release=cvs - - - character code converters. - - - - - ports-databases - release=cvs - - - Databases. - - - - - ports-deskutils - release=cvs - - - Things that used to be on the desktop before - computers were invented. - - - - - ports-devel - release=cvs - - - Development utilities. - - - - - ports-editors - release=cvs - - - Editors. - - - - - ports-emulators - release=cvs - - - Emulators for other operating systems. - - - - - ports-ftp - release=cvs - - - FTP client and server utilities. - - - - - ports-games - release=cvs - - - Games. - - - - - ports-german - release=cvs - - - German language support. - - - - - ports-graphics - release=cvs - - - Graphics utilities. - - - - - ports-japanese - release=cvs - - - Japanese language support. - - - - - ports-korean - release=cvs - - - Korean language support. - - - - - ports-lang release=cvs - - - Programming languages. - - - - - ports-mail release=cvs - - - Mail software. - - - - - ports-math release=cvs - - - Numerical computation software. - - - - - ports-mbone - release=cvs - - - MBone applications. - - - - - ports-misc release=cvs - - - Miscellaneous utilities. - - - - - ports-net release=cvs - - - Networking software. - - - - - ports-news release=cvs - - - USENET news software. - - - - - ports-palm - release=cvs - - - Software support for 3Com Palm(tm) series. - - - - - ports-plan9 - release=cvs - - - Various programs from Plan9. - - - - - ports-print - release=cvs - - - Printing software. - - - - - ports-russian - release=cvs - - - Russian language support. - - - - - ports-security - release=cvs - - - Security utilities. - - - - - ports-shells - release=cvs - - - Command line shells. - - - - - ports-sysutils - release=cvs - - - System utilities. - - - - - ports-textproc - release=cvs - - - text processing utilities (does not include - desktop publishing). - - - - - ports-vietnamese - release=cvs - - - Vietnamese language support. - - - - - ports-www release=cvs - - - Software related to the World Wide Web. - - - - - ports-x11 release=cvs - - - Ports to support the X window system. - - - - - ports-x11-clocks - release=cvs - - - X11 clocks. - - - - - ports-x11-fm - release=cvs - - - X11 file managers. - - - - - ports-x11-fonts - release=cvs - - - X11 fonts and font utilities. - - - - - ports-x11-toolkits - release=cvs - - - X11 toolkits. - - - - - ports-x11-wm - - - X11 window managers. - - - - - - - - src-all release=cvs - - - The main FreeBSD sources, excluding the - export-restricted cryptography code. - - - - src-base release=cvs - - - Miscellaneous files at the top of - /usr/src. - - - - - src-bin release=cvs - - - User utilities that may be needed in - single-user mode - (/usr/src/bin). - - - - - src-contrib - release=cvs - - - Utilities and libraries from outside the - FreeBSD project, used relatively unmodified - (/usr/src/contrib). - - - - - src-etc release=cvs - - - System configuration files - (/usr/src/etc). - - - - - src-games release=cvs - - - Games - (/usr/src/games). - - - - - src-gnu release=cvs - - - Utilities covered by the GNU Public License - (/usr/src/gnu). - - - - - src-include - release=cvs - - - Header files - (/usr/src/include). - - - - - src-kerberosIV - release=cvs - - - KerberosIV security package - (/usr/src/kerberosIV). - - - - - src-lib release=cvs - - - Libraries - (/usr/src/lib). - - - - - src-libexec - release=cvs - - - System programs normally executed by other - programs - (/usr/src/libexec). - - - - - src-release - release=cvs - - - Files required to produce a FreeBSD release - (/usr/src/release). - - - - - src-sbin release=cvs - - - System utilities for single-user mode - (/usr/src/sbin). - - - - - src-share release=cvs - - - Files that can be shared across multiple - systems - (/usr/src/share). - - - - - src-sys release=cvs - - - The kernel - (/usr/src/sys). - - - - - src-tools release=cvs - - - Various tools for the maintenance of FreeBSD - (/usr/src/tools). - - - - - src-usrbin release=cvs - - - User utilities - (/usr/src/usr.bin). - - - - - src-usrsbin - release=cvs - - - System utilities - (/usr/src/usr.sbin). - - - - - - - - www release=cvs - - - The sources for the World Wide Web data. - - - - - - - - cvs-crypto release=cvs - - - The export-restricted cryptography code. - - - - src-crypto release=cvs - - - Export-restricted utilities and libraries from - outside the FreeBSD project, used relatively unmodified - (/usr/src/crypto). - - - - - src-eBones release=cvs - - - Kerberos and DES - (/usr/src/eBones). - - - - - src-secure release=cvs - - - DES (/usr/src/secure). - - - - - - - - distrib release=self - - - The CVSup server's own configuration files. Used by CVSup - mirror sites. - - - - - gnats release=current - - - The GNATS bug-tracking database. - - - - - mail-archive release=current - - - FreeBSD mailing list archive. - - - - - www release=current - - - The installed World Wide Web data. Used by WWW mirror - sites. - - - - - - - For more information - - For the CVSup FAQ and other information about CVSup, see The CVSup - Home Page. - - Most FreeBSD-related discussion of - CVSup takes place on the &a.hackers;. - New versions of the software are announced there, as well as on the - &a.announce;. - - Questions and bug reports should be addressed to the author of - the program at cvsup-bugs@polstra.com. - - - - - - Using <command>make world</command> to rebuild your system - - Contributed by &a.nik;. - - Once you have synchronised your local source tree against a - particular version of FreeBSD (stable, - current and so on) you must then use the source tree - to rebuild the system. - - Currently, the best source of information on how to do that is a - tutorial available from http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html. - - A successor to this tutorial will be integrated into the - handbook. - - - - - 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 @@ - - - - Disks - - Contributed by &a.obrien; 26 April 1998 - - 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. - - Login as user root. After you've installed the - drive, inspect /var/run/dmesg.boot to ensure the new - disk was found. Continuing with our example, the newly added drive will - be da1 and we want to mount it on - /1. (if you are adding an IDE drive substitute - wd for da) - - 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 - dedicated mode. Otherwise, FreeBSD will have to live - with in one of the PC BIOS partitions. FreeBSD calls the PC BIOS - partitions, slices 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 - fdisk utility of the other operating system. - - In the slice case the drive will be added as - /dev/da1s1e. This is read as: SCSI disk, unit number - 1 (second SCSI disk), slice 1 (PC BIOS partition 1), and - e BSD partition. In the dedicated case, the drive - will be added simply as /dev/da1e. - - - Using sysinstall - - You may use /stand/sysinstall to partition and - label a new disk using its easy to use menus. Either login as user - root or use the su command. Run - /stand/sysinstall and enter the - Configure menu. With in the FreeBSD - Configuration Menu, scroll down and select the - Partition item. Next you should be presented with a - list of hard drives installed in your system. If you do not see - da1 listed, you need to recheck your physical - installation and dmesg output in the file - /var/run/dmesg.boot. - - Select da1 to enter the FDISK Partition - Editor. Choose A to use the entire disk - for FreeBSD. When asked if you want to remain cooperative with - any future possible operating systems, answer - YES. Write the changes to the disk using - W. Now exit the FDISK editor using - q. Next you will be asked about the Master Boot - Record. Since you are adding a disk to an already running system, - choose None. - - Next enter the Disk Label Editor. 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 a partition is used for the root - partition (/). Thus only your system disk (e.g, - the disk you boot from) should have an a partition. - The b partition is used for swap partitions, and you - may have many disks with swap partitions. The c - partition addresses the entire disk in dedicated mode, or the entire - FreeBSD slice in slice mode. The other partitions are for general - use. - - Sysinstall's Label editor favors the e partition - for non-root, non-swap partitions. With in the Label editor, create a - single file system using C. When prompted if this - will be a FS (file system) or swap, choose FS and - give a mount point (e.g, /mnt). When adding a disk - in post-install mode, Sysinstall will not create entries in - /etc/fstab for you, so the mount point you specify - isn't important. - - You are now ready to write the new label to the disk and create a - file system on it. Do this by hitting W. Ignore any - errors from Sysinstall that it could not mount the new partition. Exit - the Label Editor and Sysinstall completely. - - The last step is to edit /etc/fstab to add an - entry for your new disk. - - - - Using command line utilities - - - * Using Slices - - - - - - Dedicated - - If you will not be sharing the new drive with another operating - system, you may use the dedicated 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. - - &prompt.root; dd if=/dev/zero of=/dev/rda1 bs=1k count=1 -&prompt.root; disklabel -Brw da1 auto -&prompt.root; disklabel -e da1 # create the `e' partition -&prompt.root; newfs -d0 /dev/rda1e -&prompt.root; mkdir -p /1 -&prompt.root; vi /etc/fstab # add an entry for /dev/da1e -&prompt.root; mount /1 - - An alternate method is: - - &prompt.root; dd if=/dev/zero of=/dev/rda1 count=2 -&prompt.root; disklabel /dev/rda1 | disklabel -BrR da1 /dev/stdin -&prompt.root; newfs /dev/rda1e -&prompt.root; mkdir -p /1 -&prompt.root; vi /etc/fstab # add an entry for /dev/da1e -&prompt.root; mount /1 - - - - - * Non-traditional Drives - - - * Zip Drives - - - - - - * Jaz Drives - - - - - - * Sequest Drives - - - - - - - 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 @@ - - - - Resources on the Internet - - Contributed by &a.jkh;. - - 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. - - The most important points of contact with the FreeBSD user community - are outlined below. If you are aware of other resources not mentioned - here, please send them to the &a.doc;so that they may also be - included. - - - Mailing lists - - Though many of the FreeBSD development members read USENET, we - cannot always guarantee that we will get to your questions in a timely - fashion (or at all) if you post them only to one of the - comp.unix.bsd.freebsd.* groups. By addressing your - questions to the appropriate mailing list you will reach both us and a - concentrated FreeBSD audience, invariably assuring a better (or at least - faster) response. - - The charters for the various lists are given at the bottom of this - document. Please read the charter before joining or sending - mail to any list. 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. - - Archives are kept for all of the mailing lists and can be searched - using the FreeBSD World - Wide Web server. The keyword searchable archive offers an - excellent way of finding answers to frequently asked questions and - should be consulted before posting a question. - - - List summary - - General lists: The following are general - lists which anyone is free (and encouraged) to join: - - - - - - List - Purpose - - - - - - freebsd-advocacy - FreeBSD Evangelism - - - - freebsd-announce - Important events and project milestones - - - - freebsd-bugs - Bug reports - - - - freebsd-chat - Non-technical items related to the FreeBSD - community - - - - freebsd-current - Discussion concerning the use of - FreeBSD-current - - - - freebsd-isp - Issues for Internet Service Providers using - FreeBSD - - - - freebsd-jobs - FreeBSD employment and consulting - opportunities - - - - freebsd-newbies - New FreeBSD users activities and discussions - - - - freebsd-policy - FreeBSD Core team policy decisions. Low volume, and - read-only - - - - freebsd-questions - User questions and technical support - - - - freebsd-stable - Discussion concerning the use of - FreeBSD-stable - - - - - - Technical lists: 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. - - - - - - List - Purpose - - - - - - freebsd-afs - Porting AFS to FreeBSD - - - - freebsd-alpha - Porting FreeBSD to the Alpha - - - - freebsd-doc - Creating FreeBSD related documents - - - - freebsd-database - Discussing database use and development under - FreeBSD - - - - freebsd-emulation - Emulation of other systems such as - Linux/DOS/Windows - - - - freebsd-fs - Filesystems - - - - freebsd-hackers - General technical discussion - - - - freebsd-hardware - General discussion of hardware for running - FreeBSD - - - - freebsd-ipfw - Technical discussion concerning the redesign of the IP - firewall code - - - - freebsd-isdn - ISDN developers - - - - freebsd-java - Java developers and people porting JDKs to - FreeBSD - - - - freebsd-mobile - Discussions about mobile computing - - - - freebsd-mozilla - Porting mozilla to FreeBSD - - - - freebsd-net - Networking discussion and TCP/IP/source code - - - - freebsd-platforms - Concerning ports to non-Intel architecture - platforms - - - - freebsd-ports - Discussion of the ports collection - - - - freebsd-scsi - The SCSI subsystem - - - - freebsd-security - Security issues - - - - freebsd-small - Using FreeBSD in embedded applications - - - - freebsd-smp - Design discussions for [A]Symmetric - MultiProcessing - - - - freebsd-sparc - Porting FreeBSD to Sparc systems - - - - freebsd-tokenring - Support Token Ring in FreeBSD - - - - - - Limited lists: The following lists require - approval from core@FreeBSD.org 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. - - - - - - List - Purpose - - - - - - freebsd-admin - Administrative issues - - - - freebsd-arch - Architecture and design discussions - - - - freebsd-core - FreeBSD core team - - - - freebsd-hubs - People running mirror sites (infrastructural - support) - - - - freebsd-install - Installation development - - - - freebsd-security-notifications - Security notifications - - - - freebsd-user-groups - User group coordination - - - - - - CVS lists: The following lists are for people - interested in seeing the log messages for changes to various areas of - the source tree. They are Read-Only lists and - should not have mail sent to them. - - - - - - List - Source area - Area Description (source for) - - - - - - cvs-all - /usr/src - All changes to the tree (superset) - - - - - - - - How to subscribe - - All mailing lists live on FreeBSD.org, so to post to a given list you - simply mail to - <listname@FreeBSD.org>. It will then - be redistributed to mailing list members world-wide. - - To subscribe to a list, send mail to &a.majordomo; and include - - -subscribe <listname> [<optional address>] - - in the body of your message. For example, to subscribe yourself to - freebsd-announce, you'd do: - - &prompt.user; mail majordomo@FreeBSD.org -subscribe freebsd-announce -^D - - If you want to subscribe yourself under a different name, or - submit a subscription request for a local mailing list (this is more - efficient if you have several interested parties at one site, and - highly appreciated by us!), you would do something like: - - &prompt.user; mail majordomo@FreeBSD.org -subscribe freebsd-announce local-announce@somesite.com -^D - - Finally, it is also possible to unsubscribe yourself from a list, - get a list of other list members or see the list of mailing lists - again by sending other types of control messages to majordomo. For a - complete list of available commands, do this: - - &prompt.user; mail majordomo@FreeBSD.org -help -^D - - Again, we would like to request that you keep discussion in the - technical mailing lists on a technical track. If you are only - interested in the “high points” then it is suggested that - you join freebsd-announce, which is intended only for infrequent - traffic. - - - - List charters - - AllFreeBSD 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 postmaster@FreeBSD.org, 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. - - Rules of the road: - - - - 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 - freebsd-chat@FreeBSD.org mailing list is freely - available and should be used instead. - - - - 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. - You are still responsible for your - own cross-postings, no matter who the originator might have - been. - - - - 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. - However, 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. - - - - 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. - - - - Individual list charters: - - - - FREEBSD-AFS - - - Andrew File System - - This list is for discussion on porting and using AFS from - CMU/Transarc - - - - - FREEBSD-ADMIN - - - Administrative issues - - This list is purely for discussion of FreeBSD.org 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. - - - - - FREEBSD-ANNOUNCE - - - Important events / milestones - - This is the mailing list for people interested only in - occasional announcements of significant FreeBSD events. This - includes announcements about snapshots and other releases. It - contains announcements of new FreeBSD capabilities. It may - contain calls for volunteers etc. This is a low volume, strictly - moderated mailing list. - - - - - FREEBSD-ARCH - - - Architecture and design - discussions - - 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; - - - - How to re-vamp the build system to have several - customized builds running at the same time. - - - - What needs to be fixed with VFS to make Heidemann layers - work. - - - - How do we change the device driver interface to be able - to use the ame drivers cleanly on many buses and - architectures? - - - - How do I write a network driver? - - - - 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. - - - - - FREEBSD-BUGS - - - Bug reports - - 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 WEB - interface to it. - - - - - FREEBSD-CHAT - - - Non technical items related to the FreeBSD - community - - This list contains the overflow from the other lists about - non-technical, social information. It includes discussion about - whether Jordan looks like a toon ferret or not, whether or not - to type in capitals, who is drinking too much coffee, where the - best beer is brewed, who is brewing beer in their basement, and - so on. Occasional announcements of important events (such as - upcoming parties, weddings, births, new jobs, etc) can be made - to the technical lists, but the follow ups should be directed to - this -chat list. - - - - - FREEBSD-CORE - - - FreeBSD core team - - 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. - - - - - FREEBSD-CURRENT - - - Discussions about the use of - FreeBSD-current - - This is the mailing list for users of freebsd-current. It - includes warnings about new features coming out in -current that - will affect the users, and instructions on steps that must be - taken to remain -current. Anyone running “current” - must subscribe to this list. This is a technical mailing list - for which strictly technical content is expected. - - - - - FREEBSD-CURRENT-DIGEST - - - Discussions about the use of - FreeBSD-current - - This is the digest version of the freebsd-current mailing - list. The digest consists of all messages sent to - freebsd-current bundled together and mailed out as a single - message. The average digest size is about 40kB. This list is - Read-Only and should not be posted - to. - - - - - FREEBSD-DOC - - - Documentation project - - 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! - - - - - FREEBSD-FS - - - Filesystems - - Discussions concerning FreeBSD filesystems. This is a - technical mailing list for which strictly technical content is - expected. - - - - - FREEBSD-IPFW - - - IP Firewall - - 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. - - - - - FREEBSD-ISDN - - - ISDN Communications - - This is the mailing list for people discussing the - development of ISDN support for FreeBSD. - - - - - FREEBSD-JAVA - - - Java Development - - This is the mailing list for people discussing the - development of significant Java applications for FreeBSD and the - porting and maintenance of JDKs. - - - - - FREEBSD-HACKERS - - - Technical discussions - - This is a forum for technical discussions related to - FreeBSD. This is the primary technical mailing list. It is for - individuals actively working on FreeBSD, to bring up problems or - discuss alternative solutions. Individuals interested in - following the technical discussion are also welcome. This is a - technical mailing list for which strictly technical content is - expected. - - - - - FREEBSD-HACKERS-DIGEST - - - Technical discussions - - This is the digest version of the freebsd-hackers mailing - list. The digest consists of all messages sent to - freebsd-hackers bundled together and mailed out as a single - message. The average digest size is about 40kB. This list is - Read-Only and should not be posted - to. - - - - - FREEBSD-HARDWARE - - - General discussion of FreeBSD - hardware - - General discussion about the types of hardware that FreeBSD - runs on, various problems and suggestions concerning what to buy - or avoid. - - - - - FREEBSD-INSTALL - - - Installation discussion - - This mailing list is for discussing FreeBSD installation - development for the future releases and is closed. - - - - - FREEBSD-ISP - - - Issues for Internet Service - Providers - - 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. - - - - - FREEBSD-NEWBIES - - - Newbies activities discussion - - 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. - - - - - FREEBSD-PLATFORMS - - - Porting to Non-Intel platforms - - 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. - - - - - FREEBSD-POLICY - - - Core team policy decisions - - This is a low volume, read-only mailing list for FreeBSD - Core Team Policy decisions. - - - - - FREEBSD-PORTS - - - Discussion of - “ports” - - Discussions concerning FreeBSD's “ports - collection” (/usr/ports), proposed - ports, modifications to ports collection infrastructure and - general coordination efforts. This is a technical mailing list - for which strictly technical content is expected. - - - - - FREEBSD-QUESTIONS - - - User questions - - This is the mailing list for questions about FreeBSD. You - should not send “how to” questions to the technical - lists unless you consider the question to be pretty - technical. - - - - - FREEBSD-QUESTIONS-DIGEST - - - User questions - - This is the digest version of the freebsd-questions mailing - list. The digest consists of all messages sent to - freebsd-questions bundled together and mailed out as a single - message. The average digest size is about 40kB. - - - - - FREEBSD-SCSI - - - SCSI subsystem - - 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. - - - - - FREEBSD-SECURITY - - - Security issues - - 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. - - - - - FREEBSD-SECURITY-NOTIFICATIONS - - - Security Notifications - Notifications of FreeBSD security problems and fixes. This is - not a discussion list. The discussion list is - FreeBSD-security. - - - - - FREEBSD-SMALL - - - 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. - - - - - FREEBSD-STABLE - - - Discussions about the use of - FreeBSD-stable - - This is the mailing list for users of freebsd-stable. It - includes warnings about new features coming out in -stable that - will affect the users, and instructions on steps that must be - taken to remain -stable. Anyone running “stable” - should subscribe to this list. This is a technical mailing list - for which strictly technical content is expected. - - - - - FREEBSD-USER-GROUPS - - - User Group Coordination List - - This is the mailing list for the coordinators from each of - the local area Users Groups to discuss matters with each other - and a designated individual from the Core Team. This mail list - should be limited to meeting synopsis and coordination of - projects that span User Groups. It is a closed list. - - - - - - - - Usenet newsgroups - - In addition to two FreeBSD specific newsgroups, there are many - others in which FreeBSD is discussed or are otherwise relevant to - FreeBSD users. Keyword - searchable archives are available for some of these newsgroups - from courtesy of Warren Toomey wkt@cs.adfa.edu.au. - - - BSD specific newsgroups - - - - comp.unix.bsd.freebsd.announce - - - - comp.unix.bsd.freebsd.misc - - - - - - Other Unix newsgroups of interest - - - - comp.unix - - - - comp.unix.questions - - - - comp.unix.admin - - - - comp.unix.programmer - - - - comp.unix.shell - - - - comp.unix.user-friendly - - - - comp.security.unix - - - - comp.sources.unix - - - - comp.unix.advocacy - - - - comp.unix.misc - - - - comp.bugs.4bsd - - - - comp.bugs.4bsd.ucb-fixes - - - - comp.unix.bsd - - - - - - X Window System - - - - comp.windows.x.i386unix - - - - comp.windows.x - - - - comp.windows.x.apps - - - - comp.windows.x.announce - - - - comp.windows.x.intrinsics - - - - comp.windows.x.motif - - - - comp.windows.x.pex - - - - comp.emulators.ms-windows.wine - - - - - - - World Wide Web servers - - - - http://www.FreeBSD.org/ - — Central Server. - - - - http://www.au.FreeBSD.org/FreeBSD/ — Australia/1. - - - - http://www2.au.FreeBSD.org/FreeBSD/ — Australia/2. - - - - http://www3.au.FreeBSD.org/FreeBSD/ — Australia/3. - - - - http://www.br.FreeBSD.org/www.FreeBSD.org/ — Brazil/1. - - - - http://www2.br.FreeBSD.org/www.FreeBSD.org/ — Brazil/2. - - - - http://www3.br.FreeBSD.org/ — Brazil/3. - - - - http://www.bg.FreeBSD.org/ — Bulgaria. - - - - http://www.ca.FreeBSD.org/ — Canada/1. - - - - http://FreeBSD.kawartha.com/ — Canada/2. - - - - http://www.dk.FreeBSD.org/ — Denmark. - - - - http://www.ee.FreeBSD.org/ — Estonia. - - - - http://www.fi.FreeBSD.org/ — Finland/1. - - - - http://www2.fi.FreeBSD.org/ — Finland/2. - - - - http://www.fr.FreeBSD.org/ — France. - - - - http://www.de.FreeBSD.org/ — Germany/1. - - - - http://www1.de.FreeBSD.org/ — Germany/2. - - - - http://www.de.FreeBSD.org/ — Germany/3. - - - - http://www.hu.FreeBSD.org/ — Hungary. - - - - http://www.is.FreeBSD.org/ — Iceland. - - - - http://www.ie.FreeBSD.org/ — Ireland. - - - - http://www.jp.FreeBSD.org/www.FreeBSD.org/ — Japan. - - - - http://www.kr.FreeBSD.org/ — Korea. - - - - http://rama.asiapac.net/freebsd/ — Malaysia. - - - - http://www.nl.FreeBSD.org/ — Netherlands. - - - - http://www.no.FreeBSD.org/ — Norway. - - - - http://www.pt.FreeBSD.org/ — Portugal/1. - - - - http://www2.pt.FreeBSD.org/ — Portugal/2. - - - - http://www3.pt.FreeBSD.org/ — Portugal/3. - - - - http://www.ro.FreeBSD.org/ — Romania. - - - - http://www.ru.FreeBSD.org/ — Russia/1. - - - - http://www2.ru.FreeBSD.org/ — Russia/2. - - - - http://www3.ru.FreeBSD.org/ — Russia/3. - - - - http://www4.ru.FreeBSD.org/ — Russia/4. - - - - http://www.sk.FreeBSD.org/ — Slovak Republic. - - - - http://www.si.FreeBSD.org/ — Slovenia. - - - - http://www.es.FreeBSD.org/ — Spain. - - - - http://www.za.FreeBSD.org/ — South Africa/1. - - - - http://www2.za.FreeBSD.org/ — South Africa/2. - - - - http://www.se.FreeBSD.org/www.FreeBSD.org/ — Sweden. - - - - http://www.tr.FreeBSD.org/ — Turkey. - - - - http://www.ua.FreeBSD.org/ — Ukraine/1. - - - - http://www2.ua.FreeBSD.org/ — Ukraine/2. - - - - http://www.uk.FreeBSD.org/ — United Kingdom. - - - - http://freebsd.advansys.net/ — USA/Indiana. - - - - http://www6.FreeBSD.org/ — USA/Oregon. - - - - http://www2.FreeBSD.org/ — USA/Texas. - - - - - - Email Addresses - - 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. - - - - - - Domain - Facilities - User Group - Administrator - - - - - - ukug.uk.FreeBSD.org - Forwarding only - freebsd-users@uk.FreeBSD.org - Lee Johnston - lee@uk.FreeBSD.org - - - - - - - - Shell Accounts - - 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. - - - - - - Host - Access - Facilities - Administrator - - - - - - storm.uk.FreeBSD.org - ssh only - Read-only cvs, personal webspace, email - &a.brian - - - - dogma.freebsd-uk.eu.org - Telnet/FTP/SSH - E-Mail, Webspace, Anonymous FTP - Lee Johnston - lee@uk.FreeBSD.org - - - - - - - - - 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 @@ - - - -%man; - - -%bookinfo; - - %chapters; - %authors; - %mailing-lists; - %newsgroups; - - - -]> - - - - FreeBSD Handbook - - - - The FreeBSD Documentation Project - - - - February 1999 - - - 1995 - 1996 - 1997 - 1998 - 1999 - The FreeBSD Documentation Project - - - &bookinfo.legalnotice; - - - Welcome to FreeBSD! This handbook covers the installation and day - to day use of FreeBSD Release &rel.current;. - This manual is a work in progress 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 FreeBSD World Wide Web server. - It may also be downloaded in a variety of formats and compression - options from the FreeBSD FTP - server or one of the numerous mirror sites. You may also want to - Search the - Handbook. - - - - - Getting Started - - &chap.introduction; - &chap.install; - &chap.basics; - &chap.ports - - - - System Administration - - &chap.kernelconfig; - &chap.security; - &chap.printing; - &chap.disks; - &chap.backups; - &chap.quotas; - &chap.x11; - &chap.hw; - &chap.l10n; - - - - Network Communications - - &chap.serialcomms; - &chap.ppp-and-slip; - &chap.advanced-networking; - &chap.mail; - - - - Advanced topics - - &chap.cutting-edge; - &chap.contrib; - &chap.policies; - &chap.kernelopts; - &chap.kerneldebug; - &chap.linuxemu; - &chap.internals; - - - - Appendices - - &chap.mirrors; - &chap.bibliography; - &chap.eresources; - &chap.staff; - &chap.pgpkeys; - - - - 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 @@ - - - - PC Hardware compatibility - - 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 the kernel - configuration file section in this handbook for a list of - supported devices. - - 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 Mailing Lists 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. - - - Resources on the Internet - - 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. - - - - The Pentium Systems - Hardware Performance Guide - - - - - - Sample Configurations - - The following list of sample hardware configurations by no means - constitutes an endorsement of a given hardware vendor or product by - The FreeBSD Project. 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. - - - Jordan's Picks - - 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. - - - Motherboards - - For Pentium Pro (P6) systems, I'm quite fond of the Tyan 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. - - For the Pentium II, I'm rather partial to the ASUS P2l97-S - motherboard with the on-board Adaptec SCSI WIDE controller. - - For Pentium machines, the ASUS P55T2P4 - motherboard appears to be a good choice for mid-to-high range - Pentium server and workstation systems. - - Those wishing to build more fault-tolerant systems should also - be sure to use Parity memory or, for truly 24/7 applications, ECC - memory. - - - 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. - - - - - Disk Controllers - - This one is a bit trickier, and while I used to recommend the - Buslogic controllers - unilaterally for everything from ISA to PCI, now I tend to lean - towards the Adaptec - 1542CF for ISA, Buslogic Bt747c for EISA and Adaptec 2940UW for - PCI. - - 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). - - 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. - - - 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 CAM - support which is not yet part of FreeBSD—you have to add it, - or install from one of the CAM binary snapshot release. - - - - - Disk drives - - 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. - - - - CDROM drives - - My SCSI preferences extend to SCSI CDROM drives as well, and - while the Toshiba drives - have always been favourites of mine (in whatever speed is hot that - week), I'm still fond of my good old Plextor PX-12CS drive. It's - only a 12 speed, but it's offered excellent performance and - reliability. - - 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. - - - - CD Recordable (WORM) drives - - 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 - /usr/share/examples/worm - on your 2.2 system for example scripts used to created ISO9660 - filesystem images (with RockRidge extensions) and burn them onto an - HP6020i CDR. - - - - Tape drives - - I've had pretty good luck with both 8mm - drives from Exabyte and 4mm - (DAT) drives from HP. - - 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. - - - - Video Cards - - If you can also afford to buy a commercial X server for - US$99 from Xi Graphics, Inc. - (formerly X Inside, Inc) then I can heartily recommend the - Matrox Millenium - II card. Note that support for this card is also - excellent with the XFree86 server, which is now - at version 3.3.2. - - You also certainly can't go wrong with one of Number 9's 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. - - - - Monitors - - I have had very good luck with the Sony - Multiscan 17seII monitors, 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! - - - - Networking - - I can recommend the Intel EtherExpress Pro/100B card first and - foremost, followed by the SMC 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. - - 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. - - - - Serial - - If you're looking for high-speed serial networking solutions, - then Digi International - makes the SYNC/570 - series, with drivers now in FreeBSD-current. Emerging Technologies also - manufactures a board with T1/E1 capabilities, using software they - provide. I have no direct experience using either product, - however. - - Multiport card options are somewhat more numerous, though it has - to be said that FreeBSD's support for Cyclades'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 Stallion Technologies - apparently offers an unofficial driver for their cards at this - location. - - - - Audio - - I currently use a Creative - Labs 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). - - - - Video - - 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 Matrox Meteor 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 will not work - with motherboards based on the 440FX chipset! See the motherboard reference section for details. - In such cases, it's better to go with a BT848 based board. - - - - - - Core/Processing - - - Motherboards, busses, and chipsets - - - * ISA - - - - - - * EISA - - - - - - * VLB - - - - - - PCI - - Contributed by &a.obrien; from postings by - &a.rgrimes;. 25 April 1995. - - Continuing updates by &a.jkh;. Last - update on 26 August 1996. - - 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. - - - - Mercury: - - - 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. - - - - - Saturn-I (ie, 82424ZX at rev 0, 1 or - 2): - - - 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. - - - - - Saturn-II (ie, 82424ZX at rev 3 or - 4): - - - 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). - - - - - Neptune: - - - 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”. - - - - - Triton (ie, 430FX): - - - 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. - - - - - Triton-II (ie, 430HX): - - - All reports on motherboards using this chipset have been - favorable so far. No known problems. - - - - - Orion: - - - 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. - - - - - 440FX: - - - This Pentium - Pro 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. - - - - - - - - CPUs/FPUs - - Contributed by &a.asami;. 26 December - 1997. - - - P6 class (Pentium Pro/Pentium II) - - Both the Pentium Pro and Pentium II work fine with FreeBSD. In - fact, our main ftp site ftp.FreeBSD.org (also known - as "ftp.cdrom.com", world's largest ftp site) - runs FreeBSD on a Pentium Pro. Configurations - details are available for interested parties. - - - - Pentium class - - 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. :) - - - 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). - - - - Clock speeds - - Contributed by &a.rgrimes;. 1 October - 1996. - - Updated by &a.asami;. 27 December - 1997. - - 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: - - - - - - Rated CPU MHz - External Clock and Memory Bus MHz - External to Internal Clock Multiplier - PCI Bus Clock MHz - - - - - - 60 - 60 - 1.0 - 30 - - - - 66 - 66 - 1.0 - 33 - - - - 75 - 50 - 1.5 - 25 - - - - 90 - 60 - 1.5 - 30 - - - - 100 - 50 - 2 - 25 - - - - 100 - 66 - 1.5 - 33 - - - - 120 - 60 - 2 - 30 - - - - 133 - 66 - 2 - 33 - - - - 150 - 60 - 2.5 - 30 (Intel, AMD) - - - - 150 - 75 - 2 - 37.5 (Cyrix/IBM 6x86MX) - - - - 166 - 66 - 2.5 - 33 - - - - 180 - 60 - 3 - 30 - - - - 200 - 66 - 3 - 33 - - - - 233 - 66 - 3.5 - 33 - - - - - - - 66MHz may actually be 66.667MHz, but don't assume so. - - 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. - - - 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. - - - - The AMD K6 Bug - - 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. - - - - - * 486 class - - - - - - * 386 class - - - - - - 286 class - - Sorry, FreeBSD does not run on 80286 machines. It is nearly - impossible to run today's large full-featured UNIXes on such - hardware. - - - - - * Memory - - The minimum amount of memory you must have to install FreeBSD is 5 - MB. Once your system is up and running you can build a custom kernel that - will use less memory. If you use the boot4.flp - you can get away with having only 4 MB. - - - - * BIOS - - - - - - - Input/Output Devices - - - * Video cards - - - - - - * Sound cards - - - - - - Serial ports and multiport cards - - - The UART: What it is and how it works - - Copyright © 1996 &a.uhclem;, All Rights - Reserved. 13 January 1996. - - The Universal Asynchronous Receiver/Transmitter (UART) - controller is the key component of the serial communications - subsystem of a computer. The UART takes bytes of data and transmits - the individual bits in a sequential fashion. At the destination, a - second UART re-assembles the bits into complete bytes. - - Serial transmission is commonly used with modems and for - non-networked communication between computers, terminals and other - devices. - - There are two primary forms of serial transmission: Synchronous - and Asynchronous. Depending on the modes that are supported by the - hardware, the name of the communication sub-system will usually - include a A if it supports Asynchronous - communications, and a S if it supports - Synchronous communications. Both forms are described below. - - Some common acronyms are: - -
- UART Universal Asynchronous - Receiver/Transmitter -
- -
- USART Universal Synchronous-Asynchronous - Receiver/Transmitter -
- - - Synchronous Serial Transmission - - Synchronous serial transmission requires that the sender and - receiver share a clock with one another, or that the sender - provide a strobe or other timing signal so that the receiver knows - when to “read” the next bit of the data. In most - forms of serial Synchronous communication, if there is no data - available at a given instant to transmit, a fill character must be - sent instead so that data is always being transmitted. - Synchronous communication is usually more efficient because only - data bits are transmitted between sender and receiver, and - synchronous communication can be more more costly if extra wiring - and circuits are required to share a clock signal between the - sender and receiver. - - A form of Synchronous transmission is used with printers and - fixed disk devices in that the data is sent on one set of wires - while a clock or strobe is sent on a different wire. Printers and - fixed disk devices are not normally serial devices because most - fixed disk interface standards send an entire word of data for - each clock or strobe signal by using a separate wire for each bit - of the word. In the PC industry, these are known as Parallel - devices. - - The standard serial communications hardware in the PC does not - support Synchronous operations. This mode is described here for - comparison purposes only. - - - - Asynchronous Serial Transmission - - Asynchronous transmission allows data to be transmitted - without the sender having to send a clock signal to the receiver. - Instead, the sender and receiver must agree on timing parameters - in advance and special bits are added to each word which are used - to synchronize the sending and receiving units. - - When a word is given to the UART for Asynchronous - transmissions, a bit called the "Start Bit" is added to the - beginning of each word that is to be transmitted. The Start Bit - is used to alert the receiver that a word of data is about to be - sent, and to force the clock in the receiver into synchronization - with the clock in the transmitter. These two clocks must be - accurate enough to not have the frequency drift by more than 10% - during the transmission of the remaining bits in the word. (This - requirement was set in the days of mechanical teleprinters and is - easily met by modern electronic equipment.) - - After the Start Bit, the individual bits of the word of data - are sent, with the Least Significant Bit (LSB) being sent first. - Each bit in the transmission is transmitted for exactly the same - amount of time as all of the other bits, and the receiver - “looks” at the wire at approximately halfway through - the period assigned to each bit to determine if the bit is a - 1 or a 0. For example, if - it takes two seconds to send each bit, the receiver will examine - the signal to determine if it is a 1 or a - 0 after one second has passed, then it will - wait two seconds and then examine the value of the next bit, and - so on. - - The sender does not know when the receiver has - “looked” at the value of the bit. The sender only - knows when the clock says to begin transmitting the next bit of - the word. - - When the entire data word has been sent, the transmitter may - add a Parity Bit that the transmitter generates. The Parity Bit - may be used by the receiver to perform simple error checking. - Then at least one Stop Bit is sent by the transmitter. - - When the receiver has received all of the bits in the data - word, it may check for the Parity Bits (both sender and receiver - must agree on whether a Parity Bit is to be used), and then the - receiver looks for a Stop Bit. If the Stop Bit does not appear - when it is supposed to, the UART considers the entire word to be - garbled and will report a Framing Error to the host processor when - the data word is read. The usual cause of a Framing Error is that - the sender and receiver clocks were not running at the same speed, - or that the signal was interrupted. - - Regardless of whether the data was received correctly or not, - the UART automatically discards the Start, Parity and Stop bits. - If the sender and receiver are configured identically, these bits - are not passed to the host. - - If another word is ready for transmission, the Start Bit for - the new word can be sent as soon as the Stop Bit for the previous - word has been sent. - - Because asynchronous data is “self synchronizing”, - if there is no data to transmit, the transmission line can be - idle. - - - - Other UART Functions - - In addition to the basic job of converting data from parallel - to serial for transmission and from serial to parallel on - reception, a UART will usually provide additional circuits for - signals that can be used to indicate the state of the transmission - media, and to regulate the flow of data in the event that the - remote device is not prepared to accept more data. For example, - when the device connected to the UART is a modem, the modem may - report the presence of a carrier on the phone line while the - computer may be able to instruct the modem to reset itself or to - not take calls by 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. - - - - The RS232-C and V.24 Standards - - In most computer systems, the UART is connected to circuitry - that generates signals that comply with the EIA RS232-C - specification. There is also a CCITT standard named V.24 that - mirrors the specifications included in RS232-C. - - - RS232-C Bit Assignments (Marks and Spaces) - - In RS232-C, a value of 1 is called a - Mark and a value of 0 is - called a Space. When a communication line is - idle, the line is said to be “Marking”, or - transmitting continuous 1 values. - - The Start bit always has a value of 0 (a - Space). The Stop Bit always has a value of 1 - (a Mark). This means that there will always be a Mark (1) to - Space (0) transition on the line at the start of every word, - even when multiple word are transmitted back to back. This - guarantees that sender and receiver can resynchronize their - clocks regardless of the content of the data bits that are being - transmitted. - - The idle time between Stop and Start bits does not have to - be an exact multiple (including zero) of the bit rate of the - communication link, but most UARTs are designed this way for - simplicity. - - In RS232-C, the "Marking" signal (a 1) is - represented by a voltage between -2 VDC and -12 VDC, and a - "Spacing" signal (a 0) is represented by a - voltage between 0 and +12 VDC. The transmitter is supposed to - send +12 VDC or -12 VDC, and the receiver is supposed to allow - for some voltage loss in long cables. Some transmitters in low - power devices (like portable computers) sometimes use only +5 - VDC and -5 VDC, but these values are still acceptable to a - RS232-C receiver, provided that the cable lengths are - short. - - - - RS232-C Break Signal - - RS232-C also specifies a signal called a - Break, which is caused by sending continuous - Spacing values (no Start or Stop bits). When there is no - electricity present on the data circuit, the line is considered - to be sending Break. - - The Break signal must be of a duration - longer than the time it takes to send a complete byte plus - Start, Stop and Parity bits. Most UARTs can distinguish between - a Framing Error and a Break, but if the UART cannot do this, the - Framing Error detection can be used to identify Breaks. - - In the days of teleprinters, when numerous printers around - the country were wired in series (such as news services), any - unit could cause a Break by temporarily - opening the entire circuit so that no current flowed. This was - used to allow a location with urgent news to interrupt some - other location that was currently sending information. - - In modern systems there are two types of Break signals. If - the Break is longer than 1.6 seconds, it is considered a "Modem - Break", and some modems can be programmed to terminate the - conversation and go on-hook or enter the modems' command mode - when the modem detects this signal. If the Break is smaller - than 1.6 seconds, it signifies a Data Break and it is up to the - remote computer to respond to this signal. Sometimes this form - of Break is used as an Attention or Interrupt signal and - sometimes is accepted as a substitute for the ASCII CONTROL-C - character. - - Marks and Spaces are also equivalent to “Holes” - and “No Holes” in paper tape systems. - - - Breaks cannot be generated from paper tape or from any - other byte value, since bytes are always sent with Start and - Stop bit. The UART is usually capable of generating the - continuous Spacing signal in response to a special command - from the host processor. - - - - - RS232-C DTE and DCE Devices - - The RS232-C specification defines two types of equipment: - the Data Terminal Equipment (DTE) and the Data Carrier Equipment - (DCE). Usually, the DTE device is the terminal (or computer), - and the DCE is a modem. Across the phone line at the other end - of a conversation, the receiving modem is also a DCE device and - the computer that is connected to that modem is a DTE device. - The DCE device receives signals on the pins that the DTE device - transmits on, and vice versa. - - When two devices that are both DTE or both DCE must be - connected together without a modem or a similar media translater - between them, a NULL modem must be used. The NULL modem - electrically re-arranges the cabling so that the transmitter - output is connected to the receiver input on the other device, - and vice versa. Similar translations are performed on all of - the control signals so that each device will see what it thinks - are DCE (or DTE) signals from the other device. - - The number of signals generated by the DTE and DCE devices - are not symmetrical. The DTE device generates fewer signals for - the DCE device than the DTE device receives from the DCE. - - - - RS232-C Pin Assignments - - The EIA RS232-C specification (and the ITU equivalent, V.24) - calls for a twenty-five pin connector (usually a DB25) and - defines the purpose of most of the pins in that - connector. - - In the IBM Personal Computer and similar systems, a subset - of RS232-C signals are provided via nine pin connectors (DB9). - The signals that are not included on the PC connector deal - mainly with synchronous operation, and this transmission mode is - not supported by the UART that IBM selected for use in the IBM - PC. - - Depending on the computer manufacturer, a DB25, a DB9, or - both types of connector may be used for RS232-C communications. - (The IBM PC also uses a DB25 connector for the parallel printer - interface which causes some confusion.) - - Below is a table of the RS232-C signal assignments in the - DB25 and DB9 connectors. - - - - - - DB25 RS232-C Pin - DB9 IBM PC Pin - EIA Circuit Symbol - CCITT Circuit Symbol - Common Name - Signal Source - Description - - - - - - 1 - - - AA - 101 - PG/FG - - - Frame/Protective Ground - - - - 2 - 3 - BA - 103 - TD - DTE - Transmit Data - - - - 3 - 2 - BB - 104 - RD - DCE - Receive Data - - - - 4 - 7 - CA - 105 - RTS - DTE - Request to Send - - - - 5 - 8 - CB - 106 - CTS - DCE - Clear to Send - - - - 6 - 6 - CC - 107 - DSR - DCE - Data Set Ready - - - - 7 - 5 - AV - 102 - SG/GND - - - Signal Ground - - - - 8 - 1 - CF - 109 - DCD/CD - DCE - Data Carrier Detect - - - - 9 - - - - - - - - - - - Reserved for Test - - - - 10 - - - - - - - - - - - Reserved for Test - - - - 11 - - - - - - - - - - - Reserved for Test - - - - 12 - - - CI - 122 - SRLSD - DCE - Sec. Recv. Line Signal Detector - - - - 13 - - - SCB - 121 - SCTS - DCE - Secondary Clear to Send - - - - 14 - - - SBA - 118 - STD - DTE - Secondary Transmit Data - - - - 15 - - - DB - 114 - TSET - DCE - Trans. Sig. Element Timing - - - - 16 - - - SBB - 119 - SRD - DCE - Secondary Received Data - - - - 17 - - - DD - 115 - RSET - DCE - Receiver Signal Element Timing - - - - 18 - - - - - 141 - LOOP - DTE - Local Loopback - - - - 19 - - - SCA - 120 - SRS - DTE - Secondary Request to Send - - - - 20 - 4 - CD - 108.2 - DTR - DTE - Data Terminal Ready - - - - 21 - - - - - - - RDL - DTE - Remote Digital Loopback - - - - 22 - 9 - CE - 125 - RI - DCE - Ring Indicator - - - - 23 - - - CH - 111 - DSRS - DTE - Data Signal Rate Selector - - - - 24 - - - DA - 113 - TSET - DTE - Trans. Sig. Element Timing - - - - 25 - - - - - 142 - - - DCE - Test Mode - - - - - - - - - Bits, Baud and Symbols - - Baud is a measurement of transmission speed in asynchronous - communication. Because of advances in modem communication - technology, this term is frequently misused when describing the - data rates in newer devices. - - Traditionally, a Baud Rate represents the number of bits that - are actually being sent over the media, not the amount of data - that is actually moved from one DTE device to the other. The Baud - count includes the overhead bits Start, Stop and Parity that are - generated by the sending UART and removed by the receiving UART. - This means that seven-bit words of data actually take 10 bits to - be completely transmitted. Therefore, a modem capable of moving - 300 bits per second from one place to another can normally only - move 30 7-bit words if Parity is used and one Start and Stop bit - are present. - - If 8-bit data words are used and Parity bits are also used, - the data rate falls to 27.27 words per second, because it now - takes 11 bits to send the eight-bit words, and the modem still - only sends 300 bits per second. - - The formula for converting bytes per second into a baud rate - and vice versa was simple until error-correcting modems came - along. These modems receive the serial stream of bits from the - UART in the host computer (even when internal modems are used the - data is still frequently serialized) and converts the bits back - into bytes. These bytes are then combined into packets and sent - over the phone line using a Synchronous transmission method. This - means that the Stop, Start, and Parity bits added by the UART in - the DTE (the computer) were removed by the modem before - transmission by the sending modem. When these bytes are received - by the remote modem, the remote modem adds Start, Stop and Parity - bits to the words, converts them to a serial format and then sends - them to the receiving UART in the remote computer, who then strips - the Start, Stop and Parity bits. - - The reason all these extra conversions are done is so that the - two modems can perform error correction, which means that the - receiving modem is able to ask the sending modem to resend a block - of data that was not received with the correct checksum. This - checking is handled by the modems, and the DTE devices are usually - unaware that the process is occurring. - - By striping the Start, Stop and Parity bits, the additional - bits of data that the two modems must share between themselves to - perform error-correction are mostly concealed from the effective - transmission rate seen by the sending and receiving DTE equipment. - For example, if a modem sends ten 7-bit words to another modem - without including the Start, Stop and Parity bits, the sending - modem will be able to add 30 bits of its own information that the - receiving modem can use to do error-correction without impacting - the transmission speed of the real data. - - The use of the term Baud is further confused by modems that - perform compression. A single 8-bit word passed over the - telephone line might represent a dozen words that were transmitted - to the sending modem. The receiving modem will expand the data - back to its original content and pass that data to the receiving - DTE. - - Modern modems also include buffers that allow the rate that - bits move across the phone line (DCE to DCE) to be a different - speed than the speed that the bits move between the DTE and DCE on - both ends of the conversation. Normally the speed between the DTE - and DCE is higher than the DCE to DCE speed because of the use of - compression by the modems. - - Because the number of bits needed to describe a byte varied - during the trip between the two machines plus the differing - bits-per-seconds speeds that are used present on the DTE-DCE and - DCE-DCE links, the usage of the term Baud to describe the overall - communication speed causes problems and can misrepresent the true - transmission speed. So Bits Per Second (bps) is the correct term - to use to describe the transmission rate seen at the DCE to DCE - interface and Baud or Bits Per Second are acceptable terms to use - when a connection is made between two systems with a wired - connection, or if a modem is in use that is not performing - error-correction or compression. - - Modern high speed modems (2400, 9600, 14,400, and 19,200bps) - in reality still operate at or below 2400 baud, or more - accurately, 2400 Symbols per second. High speed modem are able to - encode more bits of data into each Symbol using a technique called - Constellation Stuffing, which is why the effective bits per second - rate of the modem is higher, but the modem continues to operate - within the limited audio bandwidth that the telephone system - provides. Modems operating at 28,800 and higher speeds have - variable Symbol rates, but the technique is the same. - - - - The IBM Personal Computer UART - - Starting with the original IBM Personal Computer, IBM selected - the National Semiconductor INS8250 UART for use in the IBM PC - Parallel/Serial Adapter. Subsequent generations of compatible - computers from IBM and other vendors continued to use the INS8250 - or improved versions of the National Semiconductor UART - family. - - - National Semiconductor UART Family Tree - - There have been several versions and subsequent generations - of the INS8250 UART. Each major version is described - below. - - - -INS8250 -> INS8250B - \ - \ - \-> INS8250A -> INS82C50A - \ - \ - \-> NS16450 -> NS16C450 - \ - \ - \-> NS16550 -> NS16550A -> PC16550D - - - - INS8250 - - - This part was used in the original IBM PC and IBM - PC/XT. The original name for this part was the INS8250 - ACE (Asynchronous Communications Element) and it is made - from NMOS technology. - - The 8250 uses eight I/O ports and has a one-byte send - and a one-byte receive buffer. This original UART has - several race conditions and other flaws. The original IBM - BIOS includes code to work around these flaws, but this - made the BIOS dependent on the flaws being present, so - subsequent parts like the 8250A, 16450 or 16550 could not - be used in the original IBM PC or IBM PC/XT. - - - - - INS8250-B - - - This is the slower speed of the INS8250 made from NMOS - technology. It contains the same problems as the original - INS8250. - - - - - INS8250A - - - An improved version of the INS8250 using XMOS - technology with various functional flaws corrected. The - INS8250A was used initially in PC clone computers by - vendors who used “clean” BIOS designs. Because - of the corrections in the chip, this part could not be - used with a BIOS compatible with the INS8250 or - INS8250B. - - - - - INS82C50A - - - This is a CMOS version (low power consumption) of the - INS8250A and has similar functional - characteristics. - - - - - NS16450 - - - Same as NS8250A with improvements so it can be used - with faster CPU bus designs. IBM used this part in the - IBM AT and updated the IBM BIOS to no longer rely on the - bugs in the INS8250. - - - - - NS16C450 - - - This is a CMOS version (low power consumption) of the - NS16450. - - - - - NS16550 - - - Same as NS16450 with a 16-byte send and receive buffer - but the buffer design was flawed and could not be reliably - be used. - - - - - NS16550A - - - Same as NS16550 with the buffer flaws corrected. The - 16550A and its successors have become the most popular - UART design in the PC industry, mainly due it its ability - to reliably handle higher data rates on operating systems - with sluggish interrupt response times. - - - - - NS16C552 - - - This component consists of two NS16C550A CMOS UARTs in - a single package. - - - - - PC16550D - - - Same as NS16550A with subtle flaws corrected. This is - revision D of the 16550 family and is the latest design - available from National Semiconductor. - - - - - - - The NS16550AF and the PC16550D are the same thing - - National reorganized their part numbering system a few years - ago, and the NS16550AFN no longer exists by that name. (If you - have a NS16550AFN, look at the date code on the part, which is a - four digit number that usually starts with a nine. The first - two digits of the number are the year, and the last two digits - are the week in that year when the part was packaged. If you - have a NS16550AFN, it is probably a few years old.) - - The new numbers are like PC16550DV, with minor differences - in the suffix letters depending on the package material and its - shape. (A description of the numbering system can be found - below.) - - It is important to understand that in some stores, you may - pay $15(US) for a NS16550AFN made in 1990 and in the next - bin are the new PC16550DN parts with minor fixes that National - has made since the AFN part was in production, the PC16550DN was - probably made in the past six months and it costs half (as low - as $5(US) in volume) as much as the NS16550AFN because they - are readily available. - - As the supply of NS16550AFN chips continues to shrink, the - price will probably continue to increase until more people - discover and accept that the PC16550DN really has the same - function as the old part number. - - - - National Semiconductor Part Numbering System - - The older NSnnnnnrqp part - numbers are now of the format - PCnnnnnrgp. - - The r is the revision field. The - current revision of the 16550 from National Semiconductor is - D. - - The p is the package-type field. - The types are: - - - - - - "F" - QFP - (quad flat pack) L lead type - - - - "N" - DIP - (dual inline package) through hole straight lead - type - - - - "V" - LPCC - (lead plastic chip carrier) J lead type - - - - - - The g is the product grade field. - If an I precedes the package-type letter, it - indicates an “industrial” grade part, which has - higher specs than a standard part but not as high as Military - Specification (Milspec) component. This is an optional - field. - - So what we used to call a NS16550AFN (DIP Package) is now - called a PC16550DN or PC16550DIN. - - - - - Other Vendors and Similar UARTs - - Over the years, the 8250, 8250A, 16450 and 16550 have been - licensed or copied by other chip vendors. In the case of the - 8250, 8250A and 16450, the exact circuit (the - “megacell”) was licensed to many vendors, including - Western Digital and Intel. Other vendors reverse-engineered the - part or produced emulations that had similar behavior. - - In internal modems, the modem designer will frequently emulate - the 8250A/16450 with the modem microprocessor, and the emulated - UART will frequently have a hidden buffer consisting of several - hundred bytes. Because of the size of the buffer, these - emulations can be as reliable as a 16550A in their ability to - handle high speed data. However, most operating systems will - still report that the UART is only a 8250A or 16450, and may not - make effective use of the extra buffering present in the emulated - UART unless special drivers are used. - - Some modem makers are driven by market forces to abandon a - design that has hundreds of bytes of buffer and instead use a - 16550A UART so that the product will compare favorably in market - comparisons even though the effective performance may be lowered - by this action. - - A common misconception is that all parts with - “16550A” written on them are identical in performance. - There are differences, and in some cases, outright flaws in most - of these 16550A clones. - - When the NS16550 was developed, the National Semiconductor - obtained several patents on the design and they also limited - licensing, making it harder for other vendors to provide a chip - with similar features. Because of the patents, reverse-engineered - designs and emulations had to avoid infringing the claims covered - by the patents. Subsequently, these copies almost never perform - exactly the same as the NS16550A or PC16550D, which are the parts - most computer and modem makers want to buy but are sometimes - unwilling to pay the price required to get the genuine - part. - - Some of the differences in the clone 16550A parts are - unimportant, while others can prevent the device from being used - at all with a given operating system or driver. These differences - may show up when using other drivers, or when particular - combinations of events occur that were not well tested or - considered in the Windows driver. This is because 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. - - National Semiconductor has made available a program named - COMTEST that performs compatibility - tests independent of any OS drivers. It should be remembered that - the purpose of this type of program is to demonstrate the flaws in - the products of the competition, so the program will report major - as well as extremely subtle differences in behavior in the part - being tested. - - In a series of tests performed by the author of this document - in 1994, components made by National Semiconductor, TI, StarTech, - and CMD as well as megacells and emulations embedded in internal - modems were tested with COMTEST. A difference count for some of - these components is listed below. Because these tests were - performed in 1994, they may not reflect the current performance of - the given product from a vendor. - - It should be noted that COMTEST normally aborts when an - excessive number or certain types of problems have been detected. - As part of this testing, COMTEST was modified so that it would not - abort no matter how many differences were encountered. - - - - - - Vendor - Part Number - Errors (aka "differences" reported) - - - - - - National - (PC16550DV) - 0 - - - - National - (NS16550AFN) - 0 - - - - National - (NS16C552V) - 0 - - - - TI - (TL16550AFN) - 3 - - - - CMD - (16C550PE) - 19 - - - - StarTech - (ST16C550J) - 23 - - - - Rockwell - Reference modem with internal 16550 or an - emulation (RC144DPi/C3000-25) - 117 - - - - Sierra - Modem with an internal 16550 - (SC11951/SC11351) - 91 - - - - - - - To date, the author of this document has not found any - non-National parts that report zero differences using the - COMTEST program. It should also be noted that National has had - five versions of the 16550 over the years and the newest parts - behave a bit differently than the classic NS16550AFN that is - considered the benchmark for functionality. COMTEST appears to - turn a blind eye to the differences within the National product - line and reports no errors on the National parts (except for the - original 16550) even when there are official erratas that - describe bugs in the A, B and C revisions of the parts, so this - bias in COMTEST must be taken into account. - - - It is important to understand that a simple count of - differences from COMTEST does not reveal a lot about what - differences are important and which are not. For example, about - half of the differences reported in the two modems listed above - that have internal UARTs were caused by the clone UARTs not - supporting five- and six-bit character modes. The real 16550, - 16450, and 8250 UARTs all support these modes and COMTEST checks - the functionality of these modes so over fifty differences are - reported. However, almost no modern modem supports five- or - six-bit characters, particularly those with error-correction and - compression capabilities. This means that the differences related - to five- and six-bit character modes can be discounted. - - Many of the differences COMTEST reports have to do with - timing. In many of the clone designs, when the host reads from - one port, the status bits in some other port may not update in the - same amount of time (some faster, some slower) as a - real NS16550AFN and COMTEST looks for these - differences. This means that the number of differences can be - misleading in that one device may only have one or two differences - but they are extremely serious, and some other device that updates - the status registers faster or slower than the reference part - (that would probably never affect the operation of a properly - written driver) could have dozens of differences reported. - - COMTEST can be used as a screening tool to alert the - administrator to the presence of potentially incompatible - components that might cause problems or have to be handled as a - special case. - - If you run COMTEST on a 16550 that is in a modem or a modem is - attached to the serial port, you need to first issue a ATE0&W - command to the modem so that the modem will not echo any of the - test characters. If you forget to do this, COMTEST will report at - least this one difference: - - Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61 - - - - 8250/16450/16550 Registers - - The 8250/16450/16550 UART occupies eight contiguous I/O port - addresses. In the IBM PC, there are two defined locations for - these eight ports and they are known collectively as COM1 and - COM2. The makers of PC-clones and add-on cards have created two - additional areas known as COM3 and COM4, but these extra COM ports - conflict with other hardware on some systems. The most common - conflict is with video adapters that provide IBM 8514 - emulation. - - COM1 is located from 0x3f8 to 0x3ff and normally uses IRQ 4 - COM2 is located from 0x2f8 to 0x2ff and normally uses IRQ 3 COM3 - is located from 0x3e8 to 0x3ef and has no standardized IRQ COM4 is - located from 0x2e8 to 0x2ef and has no standardized IRQ. - - A description of the I/O ports of the 8250/16450/16550 UART is - provided below. - - - - - - I/O Port - Access Allowed - Description - - - - - - +0x00 - write (DLAB==0) - Transmit Holding Register - (THR).Information written to this port are - treated as data words and will be transmitted by the - UART. - - - - +0x00 - read (DLAB==0) - Receive Buffer Register (RBR).Any - data words received by the UART form the serial link are - accessed by the host by reading this - port. - - - - +0x00 - write/read (DLAB==1) - Divisor Latch LSB (DLL)This value - will be divided from the master input clock (in the IBM - PC, the master clock is 1.8432MHz) and the resulting - clock will determine the baud rate of the UART. This - register holds bits 0 thru 7 of the - divisor. - - - - +0x01 - write/read (DLAB==1) - Divisor Latch MSB (DLH)This value - will be divided from the master input clock (in the IBM - PC, the master clock is 1.8432MHz) and the resulting - clock will determine the baud rate of the UART. This - register holds bits 8 thru 15 of the - divisor. - - - - +0x01 - write/read (DLAB==0) - - - - - - - - Interrupt Enable Register - (IER)The 8250/16450/16550 UART - classifies events into one of four categories. - Each category can be configured to generate an - interrupt when any of the events occurs. The - 8250/16450/16550 UART generates a single external - interrupt signal regardless of how many events in - the enabled categories have occurred. It is up to - the host processor to respond to the interrupt and - then poll the enabled interrupt categories - (usually all categories have interrupts enabled) - to determine the true cause(s) of the - interrupt. - - - - Bit 7 - Reserved, always 0. - - - - Bit 6 - Reserved, always 0. - - - - Bit 5 - Reserved, always 0. - - - - Bit 4 - Reserved, always 0. - - - - Bit 3 - Enable Modem Status Interrupt (EDSSI). Setting - this bit to "1" allows the UART to generate an - interrupt when a change occurs on one or more of the - status lines. - - - - Bit 2 - Enable Receiver Line Status Interrupt (ELSI) - Setting this bit to "1" causes the UART to generate - an interrupt when the an error (or a BREAK signal) - has been detected in the incoming data. - - - - Bit 1 - Enable Transmitter Holding Register Empty - Interrupt (ETBEI) Setting this bit to "1" causes the - UART to generate an interrupt when the UART has room - for one or more additional characters that are to be - transmitted. - - - - Bit 0 - Enable Received Data Available Interrupt - (ERBFI) Setting this bit to "1" causes the UART to - generate an interrupt when the UART has received - enough characters to exceed the trigger level of the - FIFO, or the FIFO timer has expired (stale data), or - a single character has been received when the FIFO - is disabled. - - - - - - - +0x02 - write - - - - - - - - - - - FIFO Control Register (FCR) - (This port does not exist on the 8250 and 16450 - UART.) - - - - Bit 7 - Receiver Trigger Bit #1 - - - - Bit 6 - Receiver Trigger Bit - #0These two bits control at what - point the receiver is to generate an interrupt - when the FIFO is active. - - - - 7 - 6 - How many words are received - before an interrupt is generated - - - - 0 - 0 - 1 - - - - 0 - 1 - 4 - - - - 1 - 0 - 8 - - - - 1 - 1 - 14 - - - - Bit 5 - Reserved, always 0. - - - - Bit 4 - Reserved, always 0. - - - - Bit 3 - DMA Mode Select. If Bit 0 is - set to "1" (FIFOs enabled), setting this bit changes - the operation of the -RXRDY and -TXRDY signals from - Mode 0 to Mode 1. - - - - Bit 2 - Transmit FIFO Reset. When a - "1" is written to this bit, the contents of the FIFO - are discarded. Any word currently being transmitted - will be sent intact. This function is useful in - aborting transfers. - - - - Bit 1 - Receiver FIFO Reset. When a - "1" is written to this bit, the contents of the FIFO - are discarded. Any word currently being assembled - in the shift register will be received - intact. - - - - Bit 0 - 16550 FIFO Enable. When set, - both the transmit and receive FIFOs are enabled. - Any contents in the holding register, shift - registers or FIFOs are lost when FIFOs are enabled - or disabled. - - - - - - - +0x02 - read - - - - - - - - - - - - - Interrupt Identification - Register - - - - Bit 7 - FIFOs enabled. On the - 8250/16450 UART, this bit is zero. - - - - Bit 6 - FIFOs enabled. On the - 8250/16450 UART, this bit is zero. - - - - Bit 5 - Reserved, always 0. - - - - Bit 4 - Reserved, always 0. - - - - Bit 3 - Interrupt ID Bit #2. On the - 8250/16450 UART, this bit is zero. - - - - Bit 2 - Interrupt ID Bit #1 - - - - Bit 1 - Interrupt ID Bit #0.These three - bits combine to report the category of event that - caused the interrupt that is in progress. These - categories have priorities, so if multiple - categories of events occur at the same time, the - UART will report the more important events first and - the host must resolve the events in the order they - are reported. All events that caused the current - interrupt must be resolved before any new interrupts - will be generated. (This is a limitation of the PC - architecture.) - - - - 2 - 1 - 0 - Priority - Description - - - - 0 - 1 - 1 - First - Received Error (OE, PE, BI, or - FE) - - - - 0 - 1 - 0 - Second - Received Data Available - - - - 1 - 1 - 0 - Second - Trigger level identification - (Stale data in receive buffer) - - - - 0 - 0 - 1 - Third - Transmitter has room for more - words (THRE) - - - - 0 - 0 - 0 - Fourth - Modem Status Change (-CTS, -DSR, - -RI, or -DCD) - - - - Bit 0 - Interrupt Pending Bit. If this - bit is set to "0", then at least one interrupt is - pending. - - - - - - - +0x03 - write/read - - - - - - - - - - - - - Line Control Register - (LCR) - - - - Bit 7 - Divisor Latch Access Bit - (DLAB). When set, access to the data - transmit/receive register (THR/RBR) and the - Interrupt Enable Register (IER) is disabled. Any - access to these ports is now redirected to the - Divisor Latch Registers. Setting this bit, loading - the Divisor Registers, and clearing DLAB should be - done with interrupts disabled. - - - - Bit 6 - Set Break. When set to "1", - the transmitter begins to transmit continuous - Spacing until this bit is set to "0". This - overrides any bits of characters that are being - transmitted. - - - - Bit 5 - Stick Parity. When parity is - enabled, setting this bit causes parity to always be - "1" or "0", based on the value of Bit 4. - - - - Bit 4 - Even Parity Select (EPS). When - parity is enabled and Bit 5 is "0", setting this bit - causes even parity to be transmitted and expected. - Otherwise, odd parity is used. - - - - Bit 3 - Parity Enable (PEN). When set - to "1", a parity bit is inserted between the last - bit of the data and the Stop Bit. The UART will - also expect parity to be present in the received - data. - - - - Bit 2 - Number of Stop Bits (STB). If - set to "1" and using 5-bit data words, 1.5 Stop Bits - are transmitted and expected in each data word. For - 6, 7 and 8-bit data words, 2 Stop Bits are - transmitted and expected. When this bit is set to - "0", one Stop Bit is used on each data word. - - - - Bit 1 - Word Length Select Bit #1 - (WLSB1) - - - - Bit 0 - Word Length Select Bit #0 - (WLSB0) - - - - Together these - bits specify the number of bits in each data - word. - - - - 1 - 0 - Word - Length - - - - 0 - 0 - 5 Data - Bits - - - - 0 - 1 - 6 Data - Bits - - - - 1 - 0 - 7 Data - Bits - - - - 1 - 1 - 8 Data - Bits - - - - - - - +0x04 - write/read - - - - - - - - Modem Control Register - (MCR) - - - - Bit 7 - Reserved, always 0. - - - - Bit 6 - Reserved, always 0. - - - - Bit 5 - Reserved, always 0. - - - - Bit 4 - Loop-Back Enable. When set to "1", the UART - transmitter and receiver are internally connected - together to allow diagnostic operations. In - addition, the UART modem control outputs are - connected to the UART modem control inputs. CTS is - connected to RTS, DTR is connected to DSR, OUT1 is - connected to RI, and OUT 2 is connected to - DCD. - - - - Bit 3 - OUT 2. An auxiliary output that the host - processor may set high or low. In the IBM PC serial - adapter (and most clones), OUT 2 is used to - tri-state (disable) the interrupt signal from the - 8250/16450/16550 UART. - - - - Bit 2 - OUT 1. An auxiliary output that the host - processor may set high or low. This output is not - used on the IBM PC serial adapter. - - - - Bit 1 - Request to Send (RTS). When set to "1", the - output of the UART -RTS line is Low - (Active). - - - - Bit 0 - Data Terminal Ready (DTR). When set to "1", - the output of the UART -DTR line is Low - (Active). - - - - - - - +0x05 - write/read - - - - - - - - Line Status Register - (LSR) - - - - Bit 7 - Error in Receiver FIFO. On the 8250/16450 - UART, this bit is zero. This bit is set to "1" when - any of the bytes in the FIFO have one or more of the - following error conditions: PE, FE, or BI. - - - - Bit 6 - Transmitter Empty (TEMT). When set to "1", - there are no words remaining in the transmit FIFO - or the transmit shift register. The transmitter is - completely idle. - - - - Bit 5 - Transmitter Holding Register Empty (THRE). - When set to "1", the FIFO (or holding register) now - has room for at least one additional word to - transmit. The transmitter may still be transmitting - when this bit is set to "1". - - - - Bit 4 - Break Interrupt (BI). The receiver has - detected a Break signal. - - - - Bit 3 - Framing Error (FE). A Start Bit was detected - but the Stop Bit did not appear at the expected - time. The received word is probably - garbled. - - - - Bit 2 - Parity Error (PE). The parity bit was - incorrect for the word received. - - - - Bit 1 - Overrun Error (OE). A new word was received - and there was no room in the receive buffer. The - newly-arrived word in the shift register is - discarded. On 8250/16450 UARTs, the word in the - holding register is discarded and the newly- arrived - word is put in the holding register. - - - - Bit 0 - Data Ready (DR) One or more words are in the - receive FIFO that the host may read. A word must be - completely received and moved from the shift - register into the FIFO (or holding register for - 8250/16450 designs) before this bit is set. - - - - - - - +0x06 - write/read - - - - - - - - Modem Status Register - (MSR) - - - - Bit 7 - Data Carrier Detect (DCD). Reflects the state - of the DCD line on the UART. - - - - Bit 6 - Ring Indicator (RI). Reflects the state of the - RI line on the UART. - - - - Bit 5 - Data Set Ready (DSR). Reflects the state of - the DSR line on the UART. - - - - Bit 4 - Clear To Send (CTS). Reflects the state of the - CTS line on the UART. - - - - Bit 3 - Delta Data Carrier Detect (DDCD). Set to "1" - if the -DCD line has changed state one more more - times since the last time the MSR was read by the - host. - - - - Bit 2 - Trailing Edge Ring Indicator (TERI). Set to - "1" if the -RI line has had a low to high transition - since the last time the MSR was read by the - host. - - - - Bit 1 - Delta Data Set Ready (DDSR). Set to "1" if the - -DSR line has changed state one more more times - since the last time the MSR was read by the - host. - - - - Bit 0 - Delta Clear To Send (DCTS). Set to "1" if the - -CTS line has changed state one more more times - since the last time the MSR was read by the - host. - - - - - - - +0x07 - write/read - Scratch Register (SCR). This register performs no - function in the UART. Any value can be written by the - host to this location and read by the host later - on. - - - - - - - - Beyond the 16550A UART - - Although National Semiconductor has not offered any components - compatible with the 16550 that provide additional features, - various other vendors have. Some of these components are - described below. It should be understood that to effectively - utilize these improvements, drivers may have to be provided by the - chip vendor since most of the popular operating systems do not - support features beyond those provided by the 16550. - - - - ST16650 - - - By default this part is similar to the NS16550A, but an - extended 32-byte send and receive buffer can be optionally - enabled. Made by Startech. - - - - - TIL16660 - - - By default this part behaves similar to the NS16550A, - but an extended 64-byte send and receive buffer can be - optionally enabled. Made by Texas Instruments. - - - - - Hayes ESP - - - This proprietary plug-in card contains a 2048-byte send - and receive buffer, and supports data rates to - 230.4Kbit/sec. Made by Hayes. - - - - - In addition to these “dumb” UARTs, many vendors - produce intelligent serial communication boards. This type of - design usually provides a microprocessor that interfaces with - several UARTs, processes and buffers the data, and then alerts the - main PC processor when necessary. Because the UARTs are not - directly accessed by the PC processor in this type of - communication system, it is not necessary for the vendor to use - UARTs that are compatible with the 8250, 16450, or the 16550 UART. - This leaves the designer free to components that may have better - performance characteristics. - - - - - Configuring the <devicename>sio</devicename> driver - - The sio driver provides support for - NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT - V.24) communications interfaces. Several multiport cards are - supported as well. See the &man.sio.4; - manual page for detailed technical documentation. - - - Digi International (DigiBoard) PC/8 - - Contributed by &a.awebster;. 26 August - 1995. - - Here is a config snippet from a machine with a Digi - International PC/8 with 16550. It has 8 modems connected to these - 8 lines, and they work just great. Do not forget to add - options COM_MULTIPORT or it will not work very - well! - - -device sio4 at isa? port 0x100 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 - - The trick in setting this up is that the MSB of the flags - represent the last SIO port, in this case 11 so flags are - 0xb05. - - - - Boca 16 - - Contributed by &a.whiteside;. 26 August - 1995. - - The procedures to make a Boca 16 port board with FreeBSD are - pretty straightforward, but you will need a couple things to make - it work: - - - - You either need the kernel sources installed so you can - recompile the necessary options or you will need someone else - to compile it for you. The 2.0.5 default kernel does - not come with multiport support enabled - and you will need to add a device entry for each port - anyways. - - - - Two, you will need to know the interrupt and IO setting - for your Boca Board so you can set these options properly in - the kernel. - - - - One important note — the actual UART chips for the Boca - 16 are in the connector box, not on the internal board itself. So - if you have it unplugged, probes of those ports will fail. I have - never tested booting with the box unplugged and plugging it back - in, and I suggest you do not either. - - If you do not already have a custom kernel configuration file - set up, refer to Kernel - Configuration for general procedures. The following are - the specifics for the Boca 16 board and assume you are using the - kernel name MYKERNEL and editing with vi. - - - - Add the line - - -options COM_MULTIPORT - - to the config file. - - - - Where the current device - sion lines are, you - will need to add 16 more devices. 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. - - -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 - - The flags entry must be changed from - this example unless you are using the exact same sio - assignments. Flags are set according to - 0xMYY - where M indicates the minor number - of the master port (the last port on a Boca 16) and - YY indicates if FIFO is enabled or - disabled(enabled), IRQ sharing is used(yes) and if there is an - AST/4 compatible IRQ control register(no). In this example, - flags 0x1005 indicates that - the master port is sio16. If I added another board and - assigned sio17 through sio28, the flags for all 16 ports on - that board would be 0x1C05, where 1C - indicates the minor number of the master port. Do not change - the 05 setting. - - - - Save and complete the kernel configuration, recompile, - install and reboot. Presuming you have successfully installed - the recompiled kernel and have it set to the correct address - and IRQ, your boot message should indicate the successful - probe of the Boca ports as follows: (obviously the sio - numbers, IO and IRQ could be different) - - sio1 at 0x100-0x107 flags 0x1005 on isa -sio1: type 16550A (multiport) -sio2 at 0x108-0x10f flags 0x1005 on isa -sio2: type 16550A (multiport) -sio3 at 0x110-0x117 flags 0x1005 on isa -sio3: type 16550A (multiport) -sio4 at 0x118-0x11f flags 0x1005 on isa -sio4: type 16550A (multiport) -sio5 at 0x120-0x127 flags 0x1005 on isa -sio5: type 16550A (multiport) -sio6 at 0x128-0x12f flags 0x1005 on isa -sio6: type 16550A (multiport) -sio7 at 0x130-0x137 flags 0x1005 on isa -sio7: type 16550A (multiport) -sio8 at 0x138-0x13f flags 0x1005 on isa -sio8: type 16550A (multiport) -sio9 at 0x140-0x147 flags 0x1005 on isa -sio9: type 16550A (multiport) -sio10 at 0x148-0x14f flags 0x1005 on isa -sio10: type 16550A (multiport) -sio11 at 0x150-0x157 flags 0x1005 on isa -sio11: type 16550A (multiport) -sio12 at 0x158-0x15f flags 0x1005 on isa -sio12: type 16550A (multiport) -sio13 at 0x160-0x167 flags 0x1005 on isa -sio13: type 16550A (multiport) -sio14 at 0x168-0x16f flags 0x1005 on isa -sio14: type 16550A (multiport) -sio15 at 0x170-0x177 flags 0x1005 on isa -sio15: type 16550A (multiport) -sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa -sio16: type 16550A (multiport master) - - If the messages go by too fast to see, - - &prompt.root; dmesg | more - will show you the boot messages. - - - - Next, appropriate entries in /dev for - the devices must be made using the - /dev/MAKEDEV script. After becoming - root: - - &prompt.root; cd /dev -&prompt.root; ./MAKEDEV tty1 -&prompt.root; ./MAKEDEV cua1 -(everything in between) -&prompt.root; ./MAKEDEV ttyg -&prompt.root; ./MAKEDEV cuag - - If you do not want or need callout devices for some - reason, you can dispense with making the - cua* devices. - - - - If you want a quick and sloppy way to make sure the - devices are working, you can simply plug a modem into each - port and (as root) - - &prompt.root; echo at > ttyd* - for each device you have made. You - should see the RX lights flash for each - working port. - - - - - - - Configuring the <devicename>cy</devicename> driver - - Contributed by &a.alex;. 6 June - 1996. - - The Cyclades multiport cards are based on the - cy driver instead of the usual - sio driver used by other multiport cards. - Configuration is a simple matter of: - - - - Add the cy device to your kernel configuration - (note that your irq and iomem settings may differ). - - -device cy0 at isa? tty irq 10 iomem 0xd4000 iosiz 0x2000 vector cyintr - - - - Rebuild and - install the new kernel. - - - - Make the device - nodes by typing (the following example assumes an - 8-port board): - - &prompt.root; cd /dev -&prompt.root; for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done - - - - If appropriate, add dialup - entries to /etc/ttys by - duplicating serial device (ttyd) entries and - using ttyc in place of - ttyd. For example: - - -ttyc0 "/usr/libexec/getty std.38400" unknown on insecure -ttyc1 "/usr/libexec/getty std.38400" unknown on insecure -ttyc2 "/usr/libexec/getty std.38400" unknown on insecure -… -ttyc7 "/usr/libexec/getty std.38400" unknown on insecure - - - - Reboot with the new kernel. - - - - - - Configuring the <devicename>si</devicename> driver - - Contributed by &a.nsayer;. 25 March - 1998. - - The Specialix SI/XIO and SX multiport cards use the - si driver. A single machine can - have up to 4 host cards. The following host cards - are supported: - - - ISA SI/XIO host card (2 versions) - EISA SI/XIO host card - PCI SI/XIO host card - ISA SX host card - PCI SX host card - - - Although the SX and SI/XIO host cards look markedly different, - their functionality are basically the same. The host cards do not - use I/O locations, but instead require a 32K chunk of memory. The - factory configuration for ISA cards places this at - 0xd0000-0xd7fff. - They also require an IRQ. PCI cards will, of course, autoconfigure - themselves. - - You can attach up to 4 external modules to each host card. The - external modules contain either 4 or 8 serial ports. They come in - the following varieties: - - - SI 4 or 8 port modules. Up to 57600 bps on each port - supported. - - XIO 8 port modules. Up to 115200 bps on each port - supported. One type of XIO module has 7 serial and 1 parallel - port. - - SXDC 8 port modules. Up to 921600 bps on each port - supported. Like XIO, a module is available with one parallel - port as well. - - - To configure an ISA host card, add the following line to your - kernel configuration - file, changing the numbers as appropriate: - - -device si0 at isa? tty iomem 0xd0000 irq 11 - - Valid IRQ numbers are 9, 10, 11, 12 and 15 for SX ISA host cards - and 11, 12 and 15 for SI/XIO ISA host cards. - - To configure an EISA or PCI host card, use this line: - - -device si0 - - After adding the configuration entry, rebuild and install your - new kernel. - - After rebooting with the new kernel, you need to make the device nodes in /dev. The - MAKEDEV script will take care of this for you. - Count how many total ports you have and type: - - &prompt.root; cd /dev -&prompt.root; ./MAKEDEV ttyAnn cuaAnn - - (where nn is the number of - ports) - - If you want login prompts to appear on these ports, you will - need to add lines like this to /etc/ttys: - - -ttyA01 "/usr/libexec/getty std.9600" vt100 on insecure - - - Change the terminal type as appropriate. For modems, - dialup or unknown is - fine. - - - - - * Parallel ports - - - - - - * Modems - - - - - - * Network cards - - - - - - * Keyboards - - - - - - * Mice - - - - - - * Other - - - - - - - Storage Devices - - - Using ESDI hard disks - - Copyright © 1995, &a.wilko;. 24 - September 1995. - - 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. - - 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. - - 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. - - 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. - - - Concepts of ESDI - - - Physical connections - - 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. - - 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. - - 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. - - - - Device addressing - - 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. - - On PC type controllers the first drive is set to address 0, - the second disk to address 1. Always make - sure 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. - - - - Termination - - 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. - - So, one and only 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 - not in the middle. - - - - - Using ESDI disks with FreeBSD - - Why is ESDI such a pain to get working in the first - place? - - 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. - - 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. - - - ESDI speed variants - - 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. - - 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 and drive - documentation to see if things match. - - - - Stay on track - - 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. - - 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. - - 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. - - - - Hard or soft sectoring - - 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. - - 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 unformatted 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. - - 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. - - In general, experiment with sector settings before you install - FreeBSD because you need to re-run the low-level format after each - change. - - - - Low level formatting - - 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. - - 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. - - 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). - - - - Translations - - 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!). - - 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. - - 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 all 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. - - 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). - - - 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 - - - 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. - - - - Spare sectoring - - 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. - - 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. - - The problem is that the translation from - bad to good 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. - - 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. - - - - Bad block handling - - 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 bad144 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. - - 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 bad144 list, a - replacement block (also from the end of the FreeBSD slice) is - used. In this way, the bad144 replacement - scheme presents 'perfect' media to the FreeBSD filesystems. - - There are a number of potential pitfalls associated with the - use of bad144. 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 every - 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. - - 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. - - - The restriction is not that only the root - filesystem must be within the 1024 cylinder - limit, but rather the entire slice that - contains the root filesystem. - - - - - Kernel configuration - - ESDI disks are handled by the same wddriver - as IDE and ST412 MFM disks. The wd driver - should work for all WD1003 compatible interfaces. - - 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. - - 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 /sys/i386/conf BTW). - - -# 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 - - - - - Particulars on ESDI hardware - - - Adaptec 2320 controllers - - I successfully installed FreeBSD onto a ESDI disk controlled - by a ACB-2320. No other operating system was present on the - disk. - - To do so I low level formatted the disk using - NEFMT.EXE (ftpable from - www.adaptec.com) 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 free configurable option in the system - BIOS to allow the BIOS to boot it. - - Before using NEFMT.EXE 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 bad144 - run. - - Please check carefully which - ACB-232xy variant you have. The - x is either 0 or - 2, indicating a controller without or with a - floppy controller on board. - - The y is more interesting. It can either - be a blank, a A-8 or a D. A - blank indicates a plain 10 Mbits/second controller. An - A-8 indicates a 15 Mbits/second controller - capable of handling 52 sectors/track. A D - means a 15 Mbits/second controller that can also handle drives - with > 36 sectors/track (also 52 ?). - - All variations should be capable of using 1:1 interleaving. - Use 1:1, FreeBSD is fast enough to handle it. - - - - Western Digital WD1007 controllers - - 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. - - 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 - WDFMT.EXE from www.wdc.com Running this formatted my drive - just fine. - - - - Ultrastor U14F controllers - - According to multiple reports from the net, Ultrastor ESDI - boards work OK with FreeBSD. I lack any further info on - particular settings. - - - - - Further reading - - If you intend to do some serious ESDI hacking, you might want to - have the official standard at hand: - - The latest ANSI X3T10 committee document is: Enhanced Small - Device Interface (ESDI) [X3.170-1990/X3.170a-1991] [X3T10/792D - Rev 11] - - On Usenet the newsgroup comp.periphs is a noteworthy place - to look for more info. - - The World Wide Web (WWW) also proves to be a very handy info - source: For info on Adaptec ESDI controllers see http://www.adaptec.com/. For - info on Western Digital controllers see http://www.wdc.com/. - - - - Thanks to... - - Andrew Gordon for sending me an Adaptec 2320 controller and ESDI - disk for testing. - - - - - What is SCSI? - - Copyright © 1995, &a.wilko;. July 6, - 1996. - - 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). - - 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 Further reading), with SCSI-3 - on the drawing boards. - - 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. - - 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). - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - - Components of SCSI - - 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. - - 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. - - 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. - - 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. - - - - SCSI bus types - - 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. - - In lots of SCSI related documentation there is a sort of jargon - in use to abbreviate the different bus types. A small list: - - - - FWD: Fast Wide Differential - - - - FND: Fast Narrow Differential - - - - SE: Single Ended - - - - FN: Fast Narrow - - - - etc. - - - - - With a minor amount of imagination one can usually imagine what - is meant. - - 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. - - 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). - - - 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. - - - - Single ended buses - - 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. - - 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. - - - If some devices on your bus use 'fast' to communicate your - bus must adhere to the length restrictions for fast - buses! - - - 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. - - For connector pinning and connector types please refer to the - SCSI-2 standard (see Further - reading) itself, connectors etc are listed there in - painstaking detail. - - 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. - - - - Differential buses - - 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). - - 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. - - 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. - - - - Terminators - - 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. - - 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. - - 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. - - Please keep in mind that terminators for differential and - single-ended buses are not identical. You should not - mix the two variants. - - 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: every single line on the SCSI - bus has 2 (two) terminators, one at each end of the - bus. 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.) - - 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. - - - 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). - - - 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. - - 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! - - - - Terminator power - - 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? - - 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. - - 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. - - 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. - - 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. - - In newer designs auto-restoring fuses that 'reset' themselves - after some time are sometimes used. - - - - Device addressing - - Because the SCSI bus is, ehh, a bus there must be a way to - distinguish or address the different devices connected to - it. - - 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. - - 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! - - 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). - - - 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). - - - 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.) - - 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. - - - - Bus layout - - 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”). - - 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. - - The electrical characteristics, its noise margins and - ultimately the reliability of it all are tightly related to linear - bus rule. - - Stick to the linear bus rule! - - - - - Using SCSI with FreeBSD - - - About translations, BIOSes and magic... - - As stated before, you should first make sure that you have a - electrically sound bus. - - 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. - - 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. - - 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? - - The SCSI BIOS itself presents to the system a so called - translated 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. - - 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. - - 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. - - It is very important that all operating - systems on the disk use the same translation - 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. - - 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. - - 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: - - aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> -sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512 - - Newer kernels usually do not report this information. - e.g. - - (bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2 -sd0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors) - - Why has this changed? - - 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 if the BIOS is never going - to know about this disk, (e.g. it is not a booting - disk) to supply a fictitious geometry that is convenient. - - - - SCSI subsystem design - - 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. - - 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 /sys/scsi. See the man pages in - section 4 for more details. - - 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. - - - - Kernel configuration - - 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 - /sys/i386/conf/LINT for an overview of a - kernel config file. LINT contains every - possible option you can dream of. It does - not imply LINT will - actually get you to a working kernel at all. - - 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. - - - Note that most of the EISA/PCI drivers (namely - ahb, ahc, - ncr and amd - will automatically obtain the correct parameters from the host - adapters themselves at boot time; thus, you just need to write, - for instance, controller ahc0. - - - An example loosely based on the FreeBSD 2.2.5-Release kernel - config file LINT with some added comments - (between []): - - -# 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] - - 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 only attach - them when they match the target ID and LUN specified on the - corresponding bus. - - 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. - - - 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 - no relationship with its target ID on the - SCSI bus. - - - 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. - - 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 /etc/fstab each time. - - Although the old style still works, you are - strongly 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. - - -[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 - - 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. - - Use man 4 scsi to check for the latest info - on the SCSI subsystem. For more detailed info on host adapter - drivers use eg man 4 ahc for info on the - Adaptec 294x driver. - - - - Tuning your SCSI kernel setup - - 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. - - 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: - - -options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device - - 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. - - - - Rogue SCSI devices - - 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. - - 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: - - 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 - - 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. - - 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. - /sys/scsi/st.c and - /sys/scsi/scsiconf.c for more info on how - this is done. - - 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. - - 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. - - - - Multiple LUN devices - - 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). - - 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. - - Look for a struct that is initialized like below: - - -{ - T_DIRECT, T_FIXED, "MAXTOR", "XT-4170S", "B5A", - "mx1", SC_ONE_LU -} - - 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: - - -{ - T_DIRECT, T_FIXED, "MUMBLETECH", "BRIDGE2000", "123", - "sd", SC_MORE_LUS -} - - The kernel on boot scans the inquiry data it receives against - the table and acts accordingly. See the source for more - info. - - - - Tagged command queueing - - Modern SCSI devices, particularly magnetic disks, - support what is called tagged command queuing (TCQ). - - 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. - - 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. - - 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. - - - - Busmaster host adapters - - 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. - - 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. - - 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. - - The solution is of course obvious: switch to a lower data - transfer rate and try if that works better. - - 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: - - -options "TUNE_1542" #dynamic tune of bus DMA speed - - Check the man pages for the host adapter that you use. Or - better still, use the ultimate documentation (read: driver - source). - - - - - Tracking down problems - - 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. - - - - Check for loose connectors and cables. - - - - Check and double check the location and number of your - terminators. - - - - Check if your bus has at least one supplier of terminator - power (especially with external terminators. - - - - Check if no double target IDs are used. - - - - Check if all devices to be used are powered up. - - - - Make a minimal bus config with as little devices as - possible. - - - - If possible, configure your host adapter to use slow bus - speeds. - - - - Disable tagged command queuing to make things as simple as - possible (for a NCR hostadapter based system see man - ncrcontrol) - - - - If you can compile a kernel, make one with the - SCSIDEBUG 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 /sys/scsi/scsidebug.h. 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 SCSIDEBUG is - defined). This will give you copious - debugging output with which to confuse the gurus. See - man 4 scsi for more exact information. Also - look at man 8 scsi. - - - - - - Further reading - - If you intend to do some serious SCSI hacking, you might want to - have the official standard at hand: - - Approved American National Standards can be purchased from - ANSI at - -
- 13th Floor - 11 West 42nd Street - New York - NY 10036 - Sales Dept: (212) 642-4900 -
- - - You can also buy many ANSI - standards and most committee draft documents from Global - Engineering Documents, - -
- 15 Inverness Way East - Englewood - CO, 80112-5704 - Phone: (800) 854-7179 - Outside USA and Canada: (303) 792-2181 - Fax: (303) 792- 2192 -
- - - Many X3T10 draft documents are available electronically on the - SCSI BBS (719-574-0424) and on the ncrinfo.ncr.com anonymous ftp site. - - Latest X3T10 committee documents are: - - - - AT Attachment (ATA or IDE) [X3.221-1994] - (Approved) - - - - ATA Extensions (ATA-2) [X3T10/948D Rev 2i] - - - - Enhanced Small Device Interface (ESDI) - [X3.170-1990/X3.170a-1991] - (Approved) - - - - Small Computer System Interface — 2 (SCSI-2) - [X3.131-1994] (Approved) - - - - SCSI-2 Common Access Method Transport and SCSI Interface - Module (CAM) [X3T10/792D Rev 11] - - - - Other publications that might provide you with additional - information are: - - - - “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 - - - - “Basics of SCSI”, a SCSI tutorial written by - Ancot Corporation Contact Ancot for availability information at: - Phone: (415) 322-5322 Fax: (415) 322-0455 - - - - “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 - - - - “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 - - - - “The SCSI Bench Reference”, “The SCSI - Encyclopedia”, and the “SCSI Tutor”, ENDL - Publications, 14426 Black Walnut Court, Saratoga CA, 95070 - Phone: (408) 867-6642 - - - - “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 - - - - On Usenet the newsgroups comp.periphs.scsi and comp.periphs are noteworthy places - to look for more info. You can also find the SCSI-Faq there, which - is posted periodically. - - 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. - - - - - * Disk/tape controllers - - - * SCSI - - - - - - * IDE - - - - - - * Floppy - - - - - - - Hard drives - - - SCSI hard drives - - Contributed by &a.asami;. 17 February - 1998. - - As mentioned in the SCSI 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 - SCSI 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. - - - Rotational speed - - 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. - - 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. - - (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 directly at the drive or a - properly ventilated disk enclosure.) - - 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. - - 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. - - 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. - - - - Form factor - - 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). - - - - Interface - - 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. - - 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.) - - 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). - - - - - * IDE hard drives - - - - - - - Tape drives - - Contributed by &a.jmb;. 2 July - 1996. - - - General tape access commands - - &man.mt.1; provides generic access to the tape drives. Some of - the more common commands are rewind, - erase, and status. See the - &man.mt.1; manual page for a detailed description. - - - - Controller Interfaces - - 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 Disk/tape - controllers. - - - - SCSI drives - - 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. - - 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. - - - 4mm (DAT: Digital Audio Tape) - - Archive Python - 28454 - - Archive Python - 04687 - - HP C1533A - - HP C1534A - - HP 35450A - - HP 35470A - - HP 35480A - - SDT-5000 - - Wangtek - 6200 - - - - 8mm (Exabyte) - - EXB-8200 - - EXB-8500 - - EXB-8505 - - - - QIC (Quarter-Inch Cartridge) - - Archive Ananconda - 2750 - - Archive Viper - 60 - - Archive Viper - 150 - - Archive Viper - 2525 - - Tandberg TDC - 3600 - - Tandberg TDC - 3620 - - Tandberg TDC - 3800 - - Tandberg TDC - 4222 - - Wangtek - 5525ES - - - - DLT (Digital Linear Tape) - - Digital TZ87 - - - - Mini-Cartridge - - Conner CTMS - 3200 - - Exabyte 2501 - - - - Autoloaders/Changers - - Hewlett-Packard HP C1553A - Autoloading DDS2 - - - - - * IDE drives - - - - - - Floppy drives - - Conner 420R - - - - * Parallel port drives - - - - - - Detailed Information - - - Archive Anaconda 2750 - - The boot message identifier for this drive is ARCHIVE - ANCDA 2750 28077 -003 type 1 removable SCSI 2 - - This is a QIC tape drive. - - 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. - - Data transfer rate is 350kB/s using - &man.dump.8;. Rates of 530kB/s have been reported when using - Amanda - - Production of this drive has been discontinued. - - 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. - - Two kernel code changes are required to use this drive. This - drive will not work as delivered. - - 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. - - If you are using the NCR SCSI controllers, patch the file - /usr/src/sys/pci/ncr.c (as shown below). - Build and install a new kernel. - - -*** 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, - - Reported by: &a.jmb; - - - - Archive Python 28454 - - The boot message identifier for this drive is ARCHIVE - Python 28454-XXX4ASB type 1 removable SCSI - 2 density code 0x8c, 512-byte - blocks - - This is a DDS-1 tape drive. - - Native capacity is 2.5GB on 90m tapes. - - Data transfer rate is XXX. - - This drive was repackaged by Sun Microsystems as model - 595-3067. - - Reported by: Bob Bishop rb@gid.co.uk - - 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. - - Reported by: Robert E. Seastrom - rs@seastrom.com - - - - Archive Python 04687 - - The boot message identifier for this drive is ARCHIVE - Python 04687-XXX 6580 Removable Sequential - Access SCSI-2 device - - This is a DAT-DDS-2 drive. - - Native capacity is 4GB when using 120m tapes. - - This drive supports hardware data compression. Switch 4 - controls MRS (Media Recognition System). MRS tapes have stripes - on the transparent leader. Switch 4 off - enables MRS, on disables MRS. - - Parity is controlled by switch 5. Switch 5 - on to enable parity control. Compression is - enabled with Switch 6 off. It is possible to - override compression with the SCSI MODE SELECT - command (see &man.mt.1;). - - Data transfer rate is 800kB/s. - - - - Archive Viper 60 - - The boot message identifier for this drive is ARCHIVE - VIPER 60 21116 -007 type 1 removable SCSI - 1 - - This is a QIC tape drive. - - Native capacity is 60MB. - - Data transfer rate is XXX. - - Production of this drive has been discontinued. - - Reported by: Philippe Regnauld - regnauld@hsc.fr - - - - Archive Viper 150 - - The boot message identifier for this drive is ARCHIVE - VIPER 150 21531 -004 Archive Viper 150 is a - known rogue type 1 removable SCSI - 1. A multitude of firmware revisions exist for this - drive. Your drive may report different numbers (e.g - 21247 -005. - - This is a QIC tape drive. - - 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. - - Data transfer rate is 100kB/s - - This drive reads and writes DC6150 (150MB) and DC6250 (250MB) - tapes. - - This drives quirks are known and pre-compiled into the scsi - tape device driver (&man.st.4;). - - Under FreeBSD 2.2-current, use mt blocksize - 512 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. - - Production of this drive has been discontinued. - - Reported by: Pedro A M Vazquez - vazquez@IQM.Unicamp.BR - - Mike Smith - msmith@atrad.adelaide.edu.au - - - - Archive Viper 2525 - - The boot message identifier for this drive is ARCHIVE - VIPER 2525 25462 -011 type 1 removable SCSI - 1 - - This is a QIC tape drive. - - Native capacity is 525MB. - - Data transfer rate is 180kB/s at 90 inches/sec. - - The drive reads QIC-525, QIC-150, QIC-120 and QIC-24 tapes. - Writes QIC-525, QIC-150, and QIC-120. - - Firmware revisions prior to 25462 -011 are - bug ridden and will not function properly. - - Production of this drive has been discontinued. - - - - Conner 420R - - The boot message identifier for this drive is Conner - tape. - - This is a floppy controller, minicartridge tape drive. - - Native capacity is XXXX - - Data transfer rate is XXX - - The drive uses QIC-80 tape cartridges. - - Reported by: Mark Hannon - mark@seeware.DIALix.oz.au - - - - Conner CTMS 3200 - - The boot message identifier for this drive is CONNER - CTMS 3200 7.00 type 1 removable SCSI - 2. - - This is a minicartridge tape drive. - - Native capacity is XXXX - - Data transfer rate is XXX - - The drive uses QIC-3080 tape cartridges. - - Reported by: Thomas S. Traylor - tst@titan.cs.mci.com - - - - <ulink - URL="http://www.digital.com/info/Customer-Update/931206004.txt.html">DEC TZ87</ulink> - - The boot message identifier for this drive is DEC - TZ87 (C) DEC 9206 type 1 removable SCSI - 2 density code 0x19 - - This is a DLT tape drive. - - Native capacity is 10GB. - - This drive supports hardware data compression. - - Data transfer rate is 1.2MB/s. - - 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. - - Reported by: &a.wilko; - - - - <ulink - URL="http://www.Exabyte.COM:80/Products/Minicartridge/2501/Rfeatures.html">Exabyte EXB-2501</ulink> - - The boot message identifier for this drive is EXABYTE - EXB-2501 - - This is a mini-cartridge tape drive. - - Native capacity is 1GB when using MC3000XL - minicartridges. - - Data transfer rate is XXX - - This drive can read and write DC2300 (550MB), DC2750 (750MB), - MC3000 (750MB), and MC3000XL (1GB) minicartridges. - - 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 - - &prompt.root; mt -f /dev/st0ctl.0 blocksize 1024 - - Before using a minicartridge for the first time, the - minicartridge must be formated. FreeBSD 2.1.0-RELEASE and - earlier: - - &prompt.root; /sbin/scsi -f /dev/rst0.ctl -s 600 -c "4 0 0 0 0 0" - - (Alternatively, fetch a copy of the - scsiformat shell script from FreeBSD - 2.1.5/2.2.) FreeBSD 2.1.5 and later: - - &prompt.root; /sbin/scsiformat -q -w /dev/rst0.ctl - - Right now, this drive cannot really be recommended for - FreeBSD. - - Reported by: Bob Beaulieu - ez@eztravel.com - - - - Exabyte EXB-8200 - - The boot message identifier for this drive is EXABYTE - EXB-8200 252X type 1 removable SCSI - 1 - - This is an 8mm tape drive. - - Native capacity is 2.3GB. - - Data transfer rate is 270kB/s. - - 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). - - 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. - - Production of this drive has been discontinued. - - Reported by: Mike Smith - msmith@atrad.adelaide.edu.au - - - - Exabyte EXB-8500 - - The boot message identifier for this drive is EXABYTE - EXB-8500-85Qanx0 0415 type 1 removable SCSI - 2 - - This is an 8mm tape drive. - - Native capacity is 5GB. - - Data transfer rate is 300kB/s. - - Reported by: Greg Lehey grog@lemis.de - - - - <ulink - URL="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">Exabyte EXB-8505</ulink> - - The boot message identifier for this drive is - EXABYTE EXB-85058SQANXR1 05B0 type 1 - removable SCSI 2 - - This is an 8mm tape drive which supports compression, and is - upward compatible with the EXB-5200 and EXB-8500. - - Native capacity is 5GB. - - The drive supports hardware data compression. - - Data transfer rate is 300kB/s. - - Reported by: Glen Foster - gfoster@gfoster.com - - - - Hewlett-Packard HP C1533A - - The boot message identifier for this drive is HP - C1533A 9503 type 1 removable SCSI - 2. - - This is a DDS-2 tape drive. DDS-2 means hardware data - compression and narrower tracks for increased data - capacity. - - Native capacity is 4GB when using 120m tapes. This drive - supports hardware data compression. - - Data transfer rate is 510kB/s. - - This drive is used in Hewlett-Packard's SureStore 6000eU and - 6000i tape drives and C1533A DDS-2 DAT drive. - - 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. - - - - - - switch 1 - switch 2 - Result - - - - - - On - On - Compression enabled at power-on, with host - control - - - - On - Off - Compression enabled at power-on, no host - control - - - - Off - On - Compression disabled at power-on, with host - control - - - - Off - Off - Compression disabled at power-on, no host - control - - - - - - 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. - - See HP - SureStore Tape Products and Hewlett-Packard - Disk and Tape Technical Information for more information - on configuring this drive. - - Warning: Quality control on these drives - varies greatly. One FreeBSD core-team member has returned 2 of - these drives. Neither lasted more than 5 months. - - Reported by: &a.se; - - - - Hewlett-Packard HP 1534A - - The boot message identifier for this drive is HP - HP35470A T503 type 1 removable SCSI - 2 Sequential-Access density code 0x13, - variable blocks. - - This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format. - - Native capacity is 2GB when using 90m tapes. - - Data transfer rate is 183kB/s. - - The same mechanism is used in Hewlett-Packard's SureStore - 2000i - tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT - drive and HP C1536A DDS format DAT drive. - - 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?) - - Reported by Gary Crutcher - gcrutchr@nightflight.com - - - - Hewlett-Packard HP C1553A Autoloading DDS2 - - The boot message identifier for this drive is "". - - This is a DDS-2 tape drive with a tape changer. DDS-2 means - hardware data compression and narrower tracks for increased data - capacity. - - Native capacity is 24GB when using 120m tapes. This drive - supports hardware data compression. - - Data transfer rate is 510kB/s (native). - - This drive is used in Hewlett-Packard's SureStore 12000e - tape drive. - - 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. - - There are four internal switches. These should be set: 1 ON; - 2 ON; 3 ON; 4 OFF. - - 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: - - -#!/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" - - - - Hewlett-Packard HP 35450A - - The boot message identifier for this drive is HP - HP35450A -A C620 type 1 removable SCSI - 2 Sequential-Access density code - 0x13 - - This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format. - - Native capacity is 1.2GB. - - Data transfer rate is 160kB/s. - - Reported by: mark thompson - mark.a.thompson@pobox.com - - - - Hewlett-Packard HP 35470A - - The boot message identifier for this drive is HP - HP35470A 9 09 type 1 removable SCSI - 2 - - This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format. - - Native capacity is 2GB when using 90m tapes. - - Data transfer rate is 183kB/s. - - The same mechanism is used in Hewlett-Packard's SureStore - 2000i - tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT - drive, and HP C1536A DDS format DAT drive. - - Warning: Quality control on these drives - varies greatly. One FreeBSD core-team member has returned 5 of - these drives. None lasted more than 9 months. - - Reported by: David Dawes - dawes@rf900.physics.usyd.edu.au (9 09) - - - - - Hewlett-Packard HP 35480A - - The boot message identifier for this drive is HP - HP35480A 1009 type 1 removable SCSI - 2 Sequential-Access density code - 0x13. - - This is a DDS-DC tape drive. DDS-DC is DDS-1 with hardware - data compression. DDS-1 is the original DAT tape format. - - 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 HP C1533A for the proper - switch settings. - - Data transfer rate is 183kB/s. - - This drive is used in Hewlett-Packard's SureStore 5000eU and - 5000i - tape drives and C35480A DDS format DAT drive.. - - This drive will occasionally hang during a tape eject - operation (mt offline). Pressing the front - panel button will eject the tape and bring the tape drive back to - life. - - 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. - - - - <ulink - URL="http://www.sel.sony.com/SEL/ccpg/storage/tape/t5000.html">Sony SDT-5000</ulink> - - There are at least two significantly different models: one is - a DDS-1 and the other DDS-2. The DDS-1 version is - SDT-5000 3.02. The DDS-2 version is - SONY SDT-5000 327M. The DDS-2 version has a 1MB - cache. This cache is able to keep the tape streaming in almost - any circumstances. - - The boot message identifier for this drive is SONY - SDT-5000 3.02 type 1 removable SCSI - 2 Sequential-Access density code - 0x13 - - Native capacity is 4GB when using 120m tapes. This drive - supports hardware data compression. - - Data transfer rate is depends upon the model or the drive. The - rate is 630kB/s for the SONY SDT-5000 327M - while compressing the data. For the SONY SDT-5000 - 3.02, the data transfer rate is 225kB/s. - - In order to get this drive to stream, set the blocksize to 512 - bytes (mt blocksize 512) reported by Kenneth - Merry ken@ulc199.residence.gatech.edu - - SONY SDT-5000 327M information reported by - Charles Henrich henrich@msu.edu - - Reported by: &a.jmz; - - - - Tandberg TDC 3600 - - The boot message identifier for this drive is - TANDBERG TDC 3600 =08: type 1 - removable SCSI 2 - - This is a QIC tape drive. - - Native capacity is 150/250MB. - - 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. - - Data transfer rate is 80kB/s. - - IBM and Emerald units will not work. Replacing the firmware - EPROM of these units will solve the problem. - - Reported by: Michael Smith - msmith@atrad.adelaide.edu.au - - - - Tandberg TDC 3620 - - This is very similar to the Tandberg TDC 3600 - drive. - - Reported by: &a.joerg; - - - - Tandberg TDC 3800 - - The boot message identifier for this drive is - TANDBERG TDC 3800 =04Y Removable - Sequential Access SCSI-2 device - - This is a QIC tape drive. - - Native capacity is 525MB. - - Reported by: &a.jhs; - - - - Tandberg TDC 4222 - - The boot message identifier for this drive is - TANDBERG TDC 4222 =07 type 1 removable - SCSI 2 - - This is a QIC tape drive. - - 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. - - 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 - mt to read one block from the tape, rewind the - tape, and then execute the backup program (mt fsr 1; mt - rewind; dump ...) - - 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. - - Reported by: &a.joerg; - - - - Wangtek 5525ES - - The boot message identifier for this drive is WANGTEK - 5525ES SCSI REV7 3R1 type 1 removable SCSI - 1 density code 0x11, 1024-byte - blocks - - This is a QIC tape drive. - - Native capacity is 525MB. - - Data transfer rate is 180kB/s. - - 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 (mt erase) - 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. - - This drives quirks are known and pre-compiled into the scsi - tape device driver (&man.st.4;). - - Other firmware revisions that are known to work are: - M75D - - Reported by: Marc van Kempen marc@bowtie.nl - REV73R1 Andrew Gordon - Andrew.Gordon@net-tel.co.uk - M75D - - - - Wangtek 6200 - - The boot message identifier for this drive is WANGTEK - 6200-HS 4B18 type 1 removable SCSI - 2 Sequential-Access density code - 0x13 - - This is a DDS-1 tape drive. - - Native capacity is 2GB using 90m tapes. - - Data transfer rate is 150kB/s. - - Reported by: Tony Kimball alk@Think.COM - - - - - * Problem drives - - - - - - - CD-ROM drives - - Contributed by &a.obrien;. 23 November - 1997. - - As mentioned in Jordan's - Picks Generally speaking those in The FreeBSD - Project 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. - - Another area where SCSI CDROM manufacturers are cutting corners is - adherence to the SCSI - specification. Many SCSI CDROMs will respond to multiple LUNs for its target - address. Known violators include the 6x Teac CD-56S 1.0D. - - - - * Other - - - - - - - * Other - - - - * PCMCIA - - - - - - - - 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 @@ - - - - Installing FreeBSD - - So, you would like to try out FreeBSD on your system? This section is - a quick-start guide for what you need to do. FreeBSD can be installed - from a variety of media including CD-ROM, floppy disk, magnetic tape, an - MS-DOS partition and, if you have a network connection, via anonymous ftp - or NFS. - - Regardless of the installation media you choose, you can get started - by creating the installation disks 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. - - 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). - - For more information on obtaining the latest FreeBSD distributions, - please see Obtaining FreeBSD in the - Appendix. - - So, to get the show on the road, follow these steps: - - - - Review the supported - configurations section of this installation guide to be sure - that your hardware is supported by FreeBSD. It may be helpful to make - a list of any special cards you have installed, such as SCSI - controllers, Ethernet adapters or sound cards. This list should - include relevant configuration parameters such as interrupts (IRQ) and - IO port addresses. - - - - If you are installing FreeBSD from CDROM media then you have - several different installation options: - - - - If the CD has been mastered with El Torrito boot support and - your system supports direct booting from CDROM (and many older - systems do not), simply insert the CD into - the drive and boot directly from it. - - - - 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. - - - You must do this from actual DOS and not a Windows DOS - box. - - - 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. - - - - 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 - floppies\kern.flp and - floppies\mfsroot.flp images—proceed to - step 4 for instructions on how to do this. - - - - - - If you do not have a CDROM distribution then simply read the installation - boot image information to find out what files you need to - download first. - - - - Make the installation boot disks from the image files: - - - - If you are using MS-DOS then download fdimage.exe - or get it from tools\fdimage.exe on the CDROM - and then run it like so: - - E:\> tools\fdimage floppies\kern.flp a: - - The fdimage program will format the - A: drive and then copy the - kern.flp image onto it (assuming that you are - at the top level of a FreeBSD distribution and the floppy images - live in the floppies subdirectory, as is - typically the case). - - - - If you are using a UNIX system to create the floppy - images: - - &prompt.root; dd if=kern.flp of=disk_device - - disk_device is the - /dev entry for the floppy drive. On FreeBSD - systems, this is /dev/rfd0 for the - A: drive and - /dev/rfd1 for the B: - drive. - - - - - - With the kern.flp in the - A: drive, reboot your computer. The next - request you should get is for the mfsroot.flp - floppy, after which the installation will proceed normally. - - If you do not 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. - - - - When the booting process is finished, The main FreeBSD - installation menu will be displayed. - - - - If something goes wrong… - - 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 supported - configurations section of this installation guide to be sure that - your hardware is indeed supported by FreeBSD. - - 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. - - 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. - - - Do not disable any device you will need during installation, such as - your screen (sc0). 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. - - - In the configuration mode, you can: - - - - List the device drivers installed in the kernel. - - - - Disable device drivers for hardware not present in your - system. - - - - Change the IRQ, DRQ, and IO port addresses used by a device - driver. - - - - After adjusting the kernel to match how you have your hardware - configured, type Q to continue booting with the new - settings. - - After FreeBSD has been installed, changes made in the configuration - mode will be permanent so you do not have to reconfigure every time you - boot. Even so, it is likely that you will want to build a custom kernel - to optimize the performance of your system. See Kernel configuration for more information - on creating custom kernels. - - - Supported Configurations - - FreeBSD currently runs on a wide variety of ISA, VLB, EISA and PCI - bus based PC's, ranging from 386sx to Pentium class machines (though the - 386sx is not recommended). Support for generic IDE or ESDI drive - configurations, various SCSI controller, network and serial cards is - also provided. - - A minimum of four megabytes of RAM is required to run FreeBSD. To - run the X Window System, eight megabytes of RAM is the recommended - minimum. - - Following is a list of all disk controllers and Ethernet cards - currently known to work with FreeBSD. Other configurations may very - well work, and we have simply not received any indication of - this. - - - Disk Controllers - - - - WD1003 (any generic MFM/RLL) - - - - WD1007 (any generic IDE/ESDI) - - - - IDE - - - - ATA - - - - Adaptec 1535 ISA SCSI controllers - - - - Adaptec 154x series ISA SCSI controllers - - - - Adaptec 174x series EISA SCSI controller in standard and - enhanced mode. - - - - Adaptec 274X/284X/2920C/2930U2/294x/2950/3940/3950 - (Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllers. - - - - Adaptec AIC7850, AIC7860, AIC7880, AIC789x, on-board SCSI - controllers. - - - - AdvanSys SCSI controllers (all models). - - - - BusLogic MultiMaster controllers: - - - BusLogic/Mylex "Flashpoint" adapters are NOT yet - supported. - - - - - BusLogic MultiMaster "W" Series Host Adapters: - - - - BT-948 - - - - BT-958 - - - - BT-958D - - - - - - BusLogic MultiMaster "C" Series Host Adapters: - - - - BT-946C - - - - BT-956C - - - - BT-956CD - - - - BT-445C - - - - BT-747C - - - - BT-757C - - - - BT-757CD - - - - BT-545C - - - - BT-540CF - - - - - - BusLogic MultiMaster "S" Series Host Adapters: - - - - BT-445S - - - - BT-747S - - - - BT-747D - - - - BT-757S - - - - BT-757D - - - - BT-545S - - - - BT-542D - - - - BT-742A - - - - BT-542B - - - - - - BusLogic MultiMaster "A" Series Host Adapters: - - - - BT-742A - - - - BT-542B - - - - - - AMI FastDisk controllers that are true BusLogic - MultiMaster clones are also supported. - - - - - - 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. - - - - 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. - - - - SymBios (formerly NCR) 53C810, 53C810a, 53C815, 53C820, - 53C825a, 53C860, 53C875, 53C875j, 53C885, 53C895 and 53C896 PCI - SCSI controllers: - - - - ASUS SC-200 - - - - Data Technology DTC3130 (all variants) - - - - Diamond FirePort (all) - - - - NCR cards (all) - - - - Symbios cards (all) - - - - Tekram DC390W, 390U and 390F - - - - Tyan S1365 - - - - - - QLogic 1020, 1040, 1040B, 1080, 1240 and 2100 SCSI and Fibre - Channel Adapters - - - - DTC 3290 EISA SCSI controller in 1542 emulation mode. - - - - 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. - - The following CD-ROM type systems are supported at this - time: - - - - SoundBlaster SCSI and ProAudio Spectrum SCSI - (cd) - - - - Mitsumi (all models) proprietary interface - (mcd) - - - - Matsushita/Panasonic (Creative) CR-562/CR-563 proprietary - interface (matcd) - - - - Sony proprietary interface (scd) - - - - ATAPI IDE interface (wcd) - - - - The following drivers were supported under the old SCSI subsystem, - but are NOT YET supported under the new CAM SCSI subsystem: - - - - Tekram DC390 and DC390T controllers (maybe other cards based - on the AMD 53c974 as well). - - - - NCR5380/NCR53400 ("ProAudio Spectrum") SCSI controller. - - - - UltraStor 14F, 24F and 34F SCSI controllers. - - - - Seagate ST01/02 SCSI controllers. - - - - Future Domain 8xx/950 series SCSI controllers. - - - - WD7000 SCSI controller. - - - - Adaptec 1510 series ISA SCSI controllers (not for bootable - devices) - - - - Adaptec 152x series ISA SCSI controllers - - - - Adaptec AIC-6260 and AIC-6360 based boards, which includes the - AHA-152x and SoundBlaster SCSI cards. - - - - - - Ethernet cards - - - - Allied-Telesis AT1700 and RE2000 cards - - - - 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. - - - - DEC EtherWORKS III NICs (DE203, DE204, and DE205) - - - - DEC EtherWORKS II NICs (DE200, DE201, DE202, and DE422) - - - - DEC DC21040/DC21041/DC21140 based NICs: - - - - ASUS PCI-L101-TB - - - - Accton ENI1203 - - - - Cogent EM960PCI - - - - Compex CPXPCI/32C - - - - D-Link DE-530 - - - - DEC DE435 - - - - DEC DE450 - - - - Danpex EN-9400P3 - - - - JCIS Condor JC1260 - - - - Kingston KNE100TX - - - - Linksys EtherPCI - - - - Mylex LNP101 - - - - SMC EtherPower 10/100 (Model 9332) - - - - SMC EtherPower (Model 8432) - - - - SMC EtherPower (2) - - - - Znyx ZX314 - - - - Znyx ZX342 - - - - - - DEC FDDI (DEFPA/DEFEA) NICs - - - - Fujitsu FMV-181 and FMV-182 - - - - Fujitsu MB86960A/MB86965A - - - - Intel EtherExpress - - - - Intel EtherExpress Pro/100B 100Mbit. - - - - Isolan AT 4141-0 (16 bit) - - - - Isolink 4110 (8 bit) - - - - Lucent WaveLAN wireless networking interface. - - - - Novell NE1000, NE2000, and NE2100 ethernet interface. - - - - 3Com 3C501 cards - - - - 3Com 3C503 Etherlink II - - - - 3Com 3c505 Etherlink/+ - - - - 3Com 3C507 Etherlink 16/TP - - - - 3Com 3C509, 3C579, 3C589 (PCMCIA) Etherlink III - - - - 3Com 3C590, 3C595 Etherlink III - - - - 3Com 3C90x cards. - - - - HP PC Lan Plus (27247B and 27252A) - - - - Toshiba ethernet cards - - - - PCMCIA ethernet cards from IBM and National Semiconductor are - also supported. - - - - - 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. - - - - - Miscellaneous devices - - - - AST 4 port serial card using shared IRQ. - - - - ARNET 8 port serial card using shared IRQ. - - - - BOCA IOAT66 6 port serial card using shared IRQ. - - - - BOCA 2016 16 port serial card using shared IRQ. - - - - Cyclades Cyclom-y Serial Board. - - - - STB 4 port card using shared IRQ. - - - - SDL Communications Riscom/8 Serial Board. - - - - SDL Communications RISCom/N2 and N2pci sync serial - cards. - - - - Digiboard Sync/570i high-speed sync serial card. - - - - Decision-Computer Intl. “Eight-Serial” 8 port - serial cards using shared IRQ. - - - - Adlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum, - Gravis UltraSound, Gravis UltraSound MAX and Roland MPU-401 sound - cards. - - - - Matrox Meteor video frame grabber. - - - - Creative Labs Video spigot frame grabber. - - - - Omnimedia Talisman frame grabber. - - - - Brooktree BT848 chip based frame grabbers. - - - - X-10 power controllers. - - - - PC joystick and speaker. - - - - FreeBSD does not currently support IBM's microchannel (MCA) - bus. - - - - - Preparing for the Installation - - 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. - - - Before installing from CDROM - - If your CDROM is of an unsupported type, then please skip to MS-DOS Preparation. - - There is not a lot of preparatory work that needs to be done to - successfully install from one of Walnut Creek's FreeBSD CDROMs (other - CDROM distributions may work as well, though we cannot say for certain - as we have no hand or say in how they are created). You can either - boot into the CD installation directly from DOS using Walnut Creek's - supplied install.bat batch file or you can make - boot floppies with the makeflp.bat command. - - For the easiest interface of all (from DOS), type - view. This will bring up a DOS menu utility that - leads you through all the available options. - - If you are creating the boot floppies from a UNIX machine, see - the beginning of this guide for - examples of how to create the boot floppies. - - Once you have booted from DOS or floppy, you should then be able - to select CDROM as the media type in the Media menu and load the - entire distribution from CDROM. No other types of installation media - should be required. - - After your system is fully installed and you have rebooted from - the hard disk, you can mount the CDROM at any time by typing: - mount /cdrom - - Before removing the CD again, also note that it is necessary to - first type: umount /cdrom. Do not just remove it - from the drive! - - - 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). - - - 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): - - -ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent - - Anyone with network connectivity to your machine (and permission - to log into it) can now chose a Media type of FTP and type in: - ftp://your machine - after picking “Other” in the ftp sites menu. - - - - Before installing from Floppy - - 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. - - You will need, at minimum, as many 1.44MB or 1.2MB floppies as it - takes to hold all files in the bin (binary distribution) directory. - If you are preparing these floppies under DOS, then THESE floppies - must be formatted using the MS-DOS FORMAT - command. If you are using Windows, use the Windows File Manager - format command. - - Do not trust Factory Preformatted floppies! - Format them again yourself, just to make sure. Many problems reported - by our users in the past have resulted from the use of improperly - formatted media, which is why I am taking such special care to mention - it here! - - If you are creating the floppies from another FreeBSD machine, a - format is still not a bad idea though you do not need to put a DOS - filesystem on each floppy. You can use the - disklabel and newfs commands to - put a UFS filesystem on them instead, as the following sequence of - commands (for a 3.5" 1.44MB floppy disk) illustrates: - - &prompt.root; fdformat -f 1440 fd0.1440 -&prompt.root; disklabel -w -r fd0.1440 floppy3 -&prompt.root; newfs -t 2 -u 18 -l 1 -i 65536 /dev/rfd0 - - - Use fd0.1200 and floppy5 - for 5.25" 1.2MB disks. - - - Then you can mount and write to them like any other file - system. - - After you have formatted the floppies, you will need to copy the - files onto them. The distribution files are split into chunks - conveniently sized so that 5 of them will fit on a conventional 1.44MB - floppy. Go through all your floppies, packing as many files as will - fit on each one, until you have got all the distributions you want - packed up in this fashion. Each distribution should go into a - subdirectory on the floppy, e.g.: a:\bin\bin.aa, - a:\bin\bin.ab, and so on. - - Once you come to the Media screen of the install, select - “Floppy” and you will be prompted for the rest. - - - - Before installing from a MS-DOS partition - - To prepare for installation from an MS-DOS partition, copy the - files from the distribution into a directory called - c:\freebsd. The directory tree structure of the - CDROM must be partially reproduced within this directory so we suggest - using the DOS xcopy command. For example, to - prepare for a minimal installation of FreeBSD: - - C:\> md c:\freebsd -C:\> xcopy /s e:\bin c:\freebsd\bin\ -C:\> xcopy /s e:\manpages c:\freebsd\manpages\ - - Assuming that C: is where you have free - space and E: is where your CDROM is - mounted. - - For as many DISTS you wish to install from MS-DOS - (and you have free space for), install each one under - c:\freebsd — the BIN dist - is only the minimal requirement. - - - - Before installing from QIC/SCSI Tape - - 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: - - &prompt.root; cd /freebsd/distdir -&prompt.root; tar cvf /dev/rwt0 dist1 ... dist2 - - 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 full - 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. - - - When going to do the installation, the tape must be in the drive - before booting from the boot floppy. The - installation probe may otherwise fail to find it. - - - - - Before installing over a network - - You can do network installations over 3 types of communications - links: - - - - Serial port - - - SLIP or PPP - - - - - Parallel port - - - PLIP (laplink cable) - - - - - Ethernet - - - A standard ethernet controller (includes some - PCMCIA). - - - - - SLIP support is rather primitive, and limited primarily to - hard-wired links, such as a serial cable running between a laptop - computer and another computer. The link should be hard-wired as the - SLIP installation does not currently offer a dialing capability; that - facility is provided with the PPP utility, which should be used in - preference to SLIP whenever possible. - - If you are using a modem, then PPP is almost certainly your only - choice. Make sure that you have your service provider's information - handy as you will need to know it fairly soon in the installation - process. You will need to know 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 set - authname and set authkey commands - before typing term. Refer to the user-ppp handbook and FAQ entries for further - information. If you have problems, logging can be directed to the - screen using the command set log local .... - - If a hard-wired connection to another FreeBSD (2.0R or later) - machine is available, you might also consider installing over a - “laplink” parallel port cable. The data rate over the - parallel port is much higher than what is typically possible over a - serial line (up to 50k/sec), thus resulting in a quicker - installation. - - Finally, for the fastest possible network installation, an - ethernet adaptor is always a good choice! FreeBSD supports most common - PC ethernet cards, a table of supported cards (and their required - settings) is provided in Supported - Hardware. If you are using one of the supported PCMCIA - ethernet cards, also be sure that it is plugged in - before the laptop is powered on! FreeBSD does - not, unfortunately, currently support hot insertion of PCMCIA cards - during installation. - - You will also need to know your IP address on the network, the - netmask value for your address class, and the name of your machine. - Your system administrator can tell you which values to use for your - particular network setup. If you will be referring to other hosts by - name rather than IP address, you will also need a name server and - possibly the address of a gateway (if you are using PPP, it is your - provider's IP address) to use in talking to it. If you do not know - the answers to all or most of these questions, then you should really - probably talk to your system administrator first - before trying this type of installation. - - Once you have a network link of some sort working, the - installation can continue over NFS or FTP. - - - Preparing for NFS installation - - NFS installation is fairly straight-forward: Simply copy the - FreeBSD distribution files you want onto a server somewhere and then - point the NFS media selection at it. - - If this server supports only “privileged port” - access (as is generally the default for Sun workstations), you will - need to set this option in the Options menu before installation can - proceed. - - If you have a poor quality ethernet card which suffers from very - slow transfer rates, you may also wish to toggle the appropriate - Options flag. - - In order for NFS installation to work, the server must support - subdir mounts, e.g., if your FreeBSD &rel.current; distribution - directory lives on: - ziggy:/usr/archive/stuff/FreeBSD Then - ziggy will have to allow the direct mounting of - /usr/archive/stuff/FreeBSD, not just - /usr or - /usr/archive/stuff. - - In FreeBSD's /etc/exports file, this is - controlled by the option. Other NFS - servers may have different conventions. If you are getting - Permission Denied messages from the server - then it is likely that you do not have this enabled properly. - - - - Preparing for FTP Installation - - FTP installation may be done from any mirror site containing a - reasonably up-to-date version of FreeBSD &rel.current;. A full menu - of reasonable choices from almost anywhere in the world is provided - by the FTP site menu. - - If you are installing from some other FTP site not listed in - this menu, or you are having troubles getting your name server - configured properly, you can also specify your own URL by selecting - the “Other” choice in that menu. A URL can also be a - direct IP address, so the following would work in the absence of a - name server: - - ftp://165.113.121.81/pub/FreeBSD/&rel.current;-RELEASE - - There are two FTP installation modes you can use: - - - - FTP Active - - - 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! - - - - - FTP Passive - - - 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. - - - - - - Active and passive modes are not the same as a - “proxy” connection, where a proxy FTP server is - listening and forwarding FTP requests! - - - 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 ftp.FreeBSD.org, - using the proxy FTP server foo.bar.com, - listening on port 1234. - - 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 - ftp://foo.bar.com:1234/pub/FreeBSD - - /pub/FreeBSD from ftp.FreeBSD.org is proxied under foo.bar.com, allowing you to install from - that machine (which fetch the files from - ftp.FreeBSD.org as your installation - requests them). - - - - - - Installing FreeBSD - - Once you have taken note of the appropriate preinstallation steps, - you should be able to install FreeBSD without any further - trouble. - - Should this not be true, then you may wish to go back and re-read - the relevant preparation section above for the installation media type - you are trying to use, perhaps there is a helpful hint there that you - missed the first time? If you are having hardware trouble, or FreeBSD - refuses to boot at all, read the Hardware Guide provided on the boot - floppy for a list of possible solutions. - - The FreeBSD boot 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! - - Meanwhile, you may also find the following “typical - installation sequence” to be helpful: - - - - Boot the kern.flp floppy and, when asked, - remove it and insert the mfsroot.flp 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 - kern.flp 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. - - - - Press F1. You should see some basic usage instructions on the - menu system and general navigation. If you have not used this menu - system before then please read this - thoroughly! - - - - Select the Options item and set any special preferences you may - have. - - - - 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. - - - - 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. - - - - - - MS-DOS User's Questions and Answers - - 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. - - Help! I have no space! Do I need to delete everything - first? - - 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 tools - directory on the FreeBSD CDROM or on the various FreeBSD ftp sites, to - be quite useful. - - FIPS allows you to split an existing MS-DOS partition into two - pieces, preserving the original partition and allowing you to install - onto the second free piece. You first defragment your MS-DOS partition, - using the DOS 6.xx DEFRAG utility or the Norton Disk tools, then run - FIPS. It will prompt you for the rest of the information it needs. - Afterwards, you can reboot and install FreeBSD on the new free slice. - See the Distributions menu for an estimation of how - much free space you will need for the kind of installation you - want. - - Can I use compressed MS-DOS filesystems from - FreeBSD? - - 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!). Do - not remove that file! You will probably regret it - greatly! - - It is probably better to create another uncompressed MS-DOS primary - partition and use this for communications between MS-DOS and - FreeBSD. - - Can I mount my MS-DOS extended - partitions? - - Yes. DOS extended partitions are mapped in at the end of the other - “slices” in FreeBSD, e.g. your D: - drive might be /dev/da0s5, your - E: drive /dev/da0s6, and - so on. This example assumes, of course, that your extended partition is - on SCSI drive 0. For IDE drives, substitute wd for - da appropriately. You otherwise mount extended - partitions exactly like you would mount any other DOS drive, - e.g.: - - &prompt.root; mount -t msdos /dev/da0s5 /dos_d - - - - - 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 @@ - - - - FreeBSD Internals - - - The FreeBSD Booting Process - - Contributed by &a.phk;. v1.1, April - 26th. - - 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. - - - Loading a kernel - - 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. - - - - Biosboot - - - 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. - - Biosboot can load a kernel from a FreeBSD filesystem. - - - - - Dosboot - - - 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. - - 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. - - - - - Netboot - - - Netboot will try to find a supported Ethernet card, and use - BOOTP, TFTP and NFS to find a kernel file to boot. - - - - - - - Determine the root filesystem - - 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. - - Presently we support the following types of root - filesystems: - - - - UFS - - - This is the most normal type of root filesystem. It can - reside on a floppy or on hard disk. - - - - - MSDOS - - - While this is technically possible, it is not particular - useful because of the FAT filesystem's - inability to deal with links, device nodes and other such - “UNIXisms”. - - - - - MFS - - - 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. - - - - - CD9660 - - - This is for using a CD-ROM as root filesystem. - - - - - NFS - - - This is for using a fileserver as root filesystem, basically - making it a diskless machine. - - - - - - - Initialize user-land things - - To get the user-land going, the kernel, when it has finished - initialization, will create a process with pid == 1 - and execute a program on the root filesystem; this program is normally - /sbin/init. - - You can substitute any program for /sbin/init, - as long as you keep in mind that: - - there is no stdin/out/err unless you open it yourself. If you - exit, the machine panics. Signal handling is special for pid - == 1. - - An example of this is the /stand/sysinstall - program on the installation floppy. - - - - Interesting combinations - - Boot a kernel with a MFS in it with a special - /sbin/init which... - - - - A — Using DOS - - - - - mounts your C: as - /C: - - - - Attaches C:/freebsd.fs on - /dev/vn0 - - - - mounts /dev/vn0 as - /rootfs - - - - makes symlinks - /rootfs/bin -> - /bin - /rootfs/etc -> - /etc - /rootfs/sbin -> - /sbin (etc...) - - - - Now you are running FreeBSD without repartitioning your hard - disk... - - - - - B — Using NFS - - - NFS mounts your server:~you/FreeBSD as - /nfs, chroots to /nfs - and executes /sbin/init there - - Now you are running FreeBSD diskless, even though you do not - control the NFS server... - - - - - C — Start an X-server - - - 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. - - - - - D — Using a tape - - - Takes a copy of /dev/rwd0 and writes it - to a remote tape station or fileserver. - - Now you finally get that backup you should have made a year - ago... - - - - - E — Acts as a firewall/web-server/what do I - know... - - - This is particularly interesting since you can boot from a - write- protected floppy, but still write to your root - filesystem... - - - - - - - - PC Memory Utilization - - Contributed by &a.joerg;. 16 Apr - 1995. - - A short description of how FreeBSD uses memory on the i386 - platform - - The boot sector will be loaded at 0:0x7c00, and - relocates itself immediately to 0x7c0:0. (This is - nothing magic, just an adjustment for the %cs - selector, done by an ljmp.) - - It then loads the first 15 sectors at 0x10000 - (segment BOOTSEG in the biosboot Makefile), and sets - up the stack to work below 0x1fff0. 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. - - boot2 asks for the boot file, and examines the - a.out header. It masks the file entry point - (usually 0xf0100000) by - 0x00ffffff, and loads the file there. Hence the - usual load point is 1 MB (0x00100000). During load, - the boot code toggles back and forth between real and protected mode, to - use the BIOS in real mode. - - The boot code itself uses segment selectors 0x18 - and 0x20 for %cs and - %ds/%es in protected mode, and - 0x28 to jump back into real mode. The kernel is - finally started with %cs 0x08 and - %ds/%es/%ss 0x10, which refer to - dummy descriptors covering the entire address space. - - 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. - - Contributed by &a.dg;. 16 Apr - 1995. - - 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 - 0x1000-0x9ffff 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. - - - - DMA: What it Is and How it Works - - Copyright © 1995,1997 &a.uhclem;, All Rights - Reserved. 10 December 1996. Last Update 8 October - 1997. - - 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). - - 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. - - 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. - - 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. - - 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). - - 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. - - - 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. - - - 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. - - - A Sample DMA transfer - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - - - DMA Page Registers and 16Meg address space limitations - - 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. - - 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”. - - 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. - - 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. - - - “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. - - - 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. - - 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. - - 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”. - - - 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. - - - - - DMA Operational Modes and Settings - - The 8237 DMA can be operated in several modes. The main ones - are: - - - - Single - - - 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. - - The standard PC-compatible floppy disk controller (NEC 765) - only has a one-byte buffer, so it uses this mode. - - - - - Block/Demand - - - 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. - - 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. - - 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. - - - - - Cascade - - - 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”. - - 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. - - 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. - - 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. - - Because of this wiring arrangement, only DMA channels 0, 1, - 2, 3, 5, 6 and 7 are usable with peripherals on PC/AT - systems. - - - DMA channel 0 was reserved for refresh operations in early - IBM PC computers, but is generally available for use by - peripherals in modern systems. - - - 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. - - 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 - 1 or drained to represent a - 0. Because all capacitors leak, power must - be added at regular intervals to keep the 1 - 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. - - 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. - - Bus-mastering is found in some SCSI host interfaces and - other high-performance peripheral controllers. - - - - - Autoinitialize - - - 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. - - 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. - - - - - - - Programming the DMA - - 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. - - 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. - - 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. - - 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. - - 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. - - - - DMA Port Map - - 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. - - - 0x00–0x1f DMA Controller #1 (Channels 0, 1, 2 and - 3) - - DMA Address and Count Registers - - - - - - 0x00 - write - Channel 0 starting address - - - - 0x00 - read - Channel 0 current address - - - - 0x01 - write - Channel 0 starting word count - - - - 0x01 - read - Channel 0 remaining word count - - - - 0x02 - write - Channel 1 starting address - - - - 0x02 - read - Channel 1 current address - - - - 0x03 - write - Channel 1 starting word count - - - - 0x03 - read - Channel 1 remaining word count - - - - 0x04 - write - Channel 2 starting address - - - - 0x04 - read - Channel 2 current address - - - - 0x05 - write - Channel 2 starting word count - - - - 0x05 - read - Channel 2 remaining word count - - - - 0x06 - write - Channel 3 starting address - - - - 0x06 - read - Channel 3 current address - - - - 0x07 - write - Channel 3 starting word count - - - - 0x07 - read - Channel 3 remaining word count - - - - - - DMA Command Registers - - - - - - 0x08 - write - Command Register - - - - 0x08 - read - Status Register - - - - 0x09 - write - Request Register - - - - 0x09 - read - - - - - - 0x0a - write - Single Mask Register Bit - - - - 0x0a - read - - - - - - 0x0b - write - Mode Register - - - - 0x0b - read - - - - - - 0x0c - write - Clear LSB/MSB Flip-Flop - - - - 0x0c - read - - - - - - 0x0d - write - Master Clear/Reset - - - - 0x0d - read - Temporary Register (not available on newer - versions) - - - 0x0e - write - Clear Mask Register - - - - 0x0e - read - - - - - - 0x0f - write - Write All Mask Register Bits - - - - 0x0f - read - Read All Mask Register Bits (only in Intel - 82374) - - - - - - - - 0xc0–0xdf DMA Controller #2 (Channels 4, 5, 6 and - 7) - - DMA Address and Count Registers - - - - - - 0xc0 - write - Channel 4 starting address - - - - 0xc0 - read - Channel 4 current address - - - - 0xc2 - write - Channel 4 starting word count - - - - 0xc2 - read - Channel 4 remaining word count - - - - 0xc4 - write - Channel 5 starting address - - - - 0xc4 - read - Channel 5 current address - - - - 0xc6 - write - Channel 5 starting word count - - - - 0xc6 - read - Channel 5 remaining word count - - - - 0xc8 - write - Channel 6 starting address - - - - 0xc8 - read - Channel 6 current address - - - - 0xca - write - Channel 6 starting word count - - - - 0xca - read - Channel 6 remaining word count - - - - 0xcc - write - Channel 7 starting address - - - - 0xcc - read - Channel 7 current address - - - - 0xce - write - Channel 7 starting word count - - - - 0xce - read - Channel 7 remaining word count - - - - - - DMA Command Registers - - - - - - 0xd0 - write - Command Register - - - - 0xd0 - read - Status Register - - - - 0xd2 - write - Request Register - - - - 0xd2 - read - - - - - - 0xd4 - write - Single Mask Register Bit - - - - 0xd4 - read - - - - - - 0xd6 - write - Mode Register - - - - 0xd6 - read - - - - - - 0xd8 - write - Clear LSB/MSB Flip-Flop - - - - 0xd8 - read - - - - - - 0xda - write - Master Clear/Reset - - - - 0xda - read - Temporary Register (not present in Intel - 82374) - - - - 0xdc - write - Clear Mask Register - - - - 0xdc - read - - - - - - 0xde - write - Write All Mask Register Bits - - - - 0xdf - read - Read All Mask Register Bits (only in Intel - 82374) - - - - - - - - 0x80–0x9f DMA Page Registers - - - - - - 0x87 - r/w - Channel 0 Low byte (23-16) page Register - - - - 0x83 - r/w - Channel 1 Low byte (23-16) page Register - - - - 0x81 - r/w - Channel 2 Low byte (23-16) page Register - - - - 0x82 - r/w - Channel 3 Low byte (23-16) page Register - - - - 0x8b - r/w - Channel 5 Low byte (23-16) page Register - - - - 0x89 - r/w - Channel 6 Low byte (23-16) page Register - - - - 0x8a - r/w - Channel 7 Low byte (23-16) page Register - - - - 0x8f - r/w - Low byte page Refresh - - - - - - - - 0x400–0x4ff 82374 Enhanced DMA Registers - - 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. - - 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 after - 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. - - - - - - 0x401 - r/w - Channel 0 High byte (bits 23-16) word count - - - - 0x403 - r/w - Channel 1 High byte (bits 23-16) word count - - - - 0x405 - r/w - Channel 2 High byte (bits 23-16) word count - - - - 0x407 - r/w - Channel 3 High byte (bits 23-16) word count - - - - 0x4c6 - r/w - Channel 5 High byte (bits 23-16) word count - - - - 0x4ca - r/w - Channel 6 High byte (bits 23-16) word count - - - - 0x4ce - r/w - Channel 7 High byte (bits 23-16) word count - - - - 0x487 - r/w - Channel 0 High byte (bits 31-24) page Register - - - - 0x483 - r/w - Channel 1 High byte (bits 31-24) page Register - - - - 0x481 - r/w - Channel 2 High byte (bits 31-24) page Register - - - - 0x482 - r/w - Channel 3 High byte (bits 31-24) page Register - - - - 0x48b - r/w - Channel 5 High byte (bits 31-24) page Register - - - - 0x489 - r/w - Channel 6 High byte (bits 31-24) page Register - - - - 0x48a - r/w - Channel 6 High byte (bits 31-24) page Register - - - - 0x48f - r/w - High byte page Refresh - - - - 0x4e0 - r/w - Channel 0 Stop Register (bits 7-2) - - - - 0x4e1 - r/w - Channel 0 Stop Register (bits 15-8) - - - - 0x4e2 - r/w - Channel 0 Stop Register (bits 23-16) - - - - 0x4e4 - r/w - Channel 1 Stop Register (bits 7-2) - - - - 0x4e5 - r/w - Channel 1 Stop Register (bits 15-8) - - - - 0x4e6 - r/w - Channel 1 Stop Register (bits 23-16) - - - - 0x4e8 - r/w - Channel 2 Stop Register (bits 7-2) - - - - 0x4e9 - r/w - Channel 2 Stop Register (bits 15-8) - - - - 0x4ea - r/w - Channel 2 Stop Register (bits 23-16) - - - - 0x4ec - r/w - Channel 3 Stop Register (bits 7-2) - - - - 0x4ed - r/w - Channel 3 Stop Register (bits 15-8) - - - - 0x4ee - r/w - Channel 3 Stop Register (bits 23-16) - - - - 0x4f4 - r/w - Channel 5 Stop Register (bits 7-2) - - - - 0x4f5 - r/w - Channel 5 Stop Register (bits 15-8) - - - - 0x4f6 - r/w - Channel 5 Stop Register (bits 23-16) - - - - 0x4f8 - r/w - Channel 6 Stop Register (bits 7-2) - - - - 0x4f9 - r/w - Channel 6 Stop Register (bits 15-8) - - - - 0x4fa - r/w - Channel 6 Stop Register (bits 23-16) - - - - 0x4fc - r/w - Channel 7 Stop Register (bits 7-2) - - - - 0x4fd - r/w - Channel 7 Stop Register (bits 15-8) - - - - 0x4fe - r/w - Channel 7 Stop Register (bits 23-16) - - - - 0x40a - write - Channels 0-3 Chaining Mode Register - - - - 0x40a - read - Channel Interrupt Status Register - - - - 0x4d4 - write - Channels 4-7 Chaining Mode Register - - - - 0x4d4 - read - Chaining Mode Status - - - - 0x40c - read - Chain Buffer Expiration Control Register - - - - 0x410 - write - Channel 0 Scatter-Gather Command Register - - - - 0x411 - write - Channel 1 Scatter-Gather Command Register - - - - 0x412 - write - Channel 2 Scatter-Gather Command Register - - - - 0x413 - write - Channel 3 Scatter-Gather Command Register - - - - 0x415 - write - Channel 5 Scatter-Gather Command Register - - - - 0x416 - write - Channel 6 Scatter-Gather Command Register - - - - 0x417 - write - Channel 7 Scatter-Gather Command Register - - - - 0x418 - read - Channel 0 Scatter-Gather Status Register - - - - 0x419 - read - Channel 1 Scatter-Gather Status Register - - - - 0x41a - read - Channel 2 Scatter-Gather Status Register - - - - 0x41b - read - Channel 3 Scatter-Gather Status Register - - - - 0x41d - read - Channel 5 Scatter-Gather Status Register - - - - 0x41e - read - Channel 5 Scatter-Gather Status Register - - - - 0x41f - read - Channel 7 Scatter-Gather Status Register - - - - 0x420-0x423 - r/w - Channel 0 Scatter-Gather Descriptor Table Pointer - Register - - - - 0x424-0x427 - r/w - Channel 1 Scatter-Gather Descriptor Table Pointer - Register - - - - 0x428-0x42b - r/w - Channel 2 Scatter-Gather Descriptor Table Pointer - Register - - - - 0x42c-0x42f - r/w - Channel 3 Scatter-Gather Descriptor Table Pointer - Register - - - - 0x434-0x437 - r/w - Channel 5 Scatter-Gather Descriptor Table Pointer - Register - - - - 0x438-0x43b - r/w - Channel 6 Scatter-Gather Descriptor Table Pointer - Register - - - - 0x43c-0x43f - r/w - Channel 7 Scatter-Gather Descriptor Table Pointer - Register - - - - - - - - - - The FreeBSD VM System - - Contributed by &a.dillon;. 6 Feb 1999 - - - Management of physical - memory—<literal>vm_page_t</literal> - - Physical memory is managed on a page-by-page basis through the - vm_page_t structure. Pages of physical memory are - categorized through the placement of their respective - vm_page_t structures on one of several paging - queues. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - - - The unified buffer - cache—<literal>vm_object_t</literal> - - 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. - - VM objects can be shadowed. 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. - - It should be noted that a vm_page_t 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. - - - - Filesystem I/O—<literal>struct buf</literal> - - 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. - - The entities used to manage this are known as filesystem buffers, - struct buf's, and also known as - bp'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. - - 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 - vm_page_t'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. - - - - Mapping Page Tables - vm_map_t, vm_entry_t - - 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. - - FreeBSD associates portions of vm_objects with address ranges in - virtual memory through vm_map_t and - vm_entry_t structures. Page tables are directly - synthesized from the - vm_map_t/vm_entry_t/ - vm_object_t hierarchy. Remember when I mentioned - that physical pages are only directly associated with a - vm_object. Well, that isn't quite true. - vm_page_t's are also linked into page tables that - they are actively associated with. One vm_page_t - can be linked into several pmaps, as page tables - are called. However, the hierarchical association holds so all - references to the same page in the same object reference the same - vm_page_t and thus give us buffer cache unification - across the board. - - - - KVM Memory Mapping - - 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 struct buf entities. - - 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. - - KVM is managed through several mechanisms. The main mechanism - used to manage KVM is the zone allocator. 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 vmstat -m to get an - overview of current KVM utilization broken down by zone. - - - - Tuning the FreeBSD VM system - - 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 maxusers and - NMBCLUSTERS kernel config options. That is, kernel - compilation options specified in (typically) - /usr/src/sys/i386/conf/CONFIG_FILE. - A description of all available kernel configuration options can be - found in /usr/src/sys/i386/conf/LINT. - - In a large system configuration you may wish to increase - maxusers. Values typically range from 10 to 128. - Note that raising maxusers 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 NMBCLUSTERS, to increase specific - resources. - - If your system is going to use the network heavily, you may want - to increase NMBCLUSTERS. Typical values range from - 1024 to 4096. - - The NBUF 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 - not try to specify an NBUF - 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. - - By default, FreeBSD kernels are not optimized. You can set - debugging and optimization flags with the - makeoptions directive in the kernel configuration. - Note that you should not use unless you can - accommodate the large (typically 7 MB+) kernels that result. - - makeoptions DEBUG="-g" -makeoptions COPTFLAGS="-O2 -pipe" - - 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. - - Run time VM and system tuning is relatively straightforward. - First, use softupdates on your UFS/FFS filesystems whenever possible. - /usr/src/contrib/sys/softupdates/README contains - instructions (and restrictions) on how to configure it up. - - 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 /var/crash must - have sufficient free space to hold the dump. - - 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. - - - - - - 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 @@ - - - - Introduction - - 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 - FreeBSD in a nutshell. For a history of - the project, read a brief history of FreeBSD. - To see a description of the latest release, read about the current release. If you are - interested in contributing something to the FreeBSD project (code, - equipment, sacks of unmarked bills), please see about contributing to FreeBSD. - - - FreeBSD in a Nutshell - - 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: - - - - Preemptive multitasking with dynamic - priority adjustment to ensure smooth and fair sharing of the - computer between applications and users. - - - - Multiuser 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. - - - - Complete TCP/IP networking 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. - - - - Memory protection ensures that applications - (or users) cannot interfere with each other. One application - crashing will not affect others in any way. - - - - FreeBSD is a 32-bit operating system and - was designed as such from the ground up. - - - - The industry standard X Window System - (X11R6) provides a graphical user interface (GUI) for the cost of a - common VGA card and monitor and comes with full sources. - - - - Binary compatibility with many programs - built for SCO, BSDI, NetBSD, Linux and 386BSD. - - - - Hundreds of ready-to-run applications are - available from the FreeBSD ports and - packages collection. Why search the net when - you can find it all right here? - - - - Thousands of additional and easy-to-port - 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. - - - - Demand paged virtual memory and - “merged VM/buffer cache” design efficiently satisfies - applications with large appetites for memory while still maintaining - interactive response to other users. - - - - Shared libraries (the Unix equivalent of - MS-Windows DLLs) provide for efficient use of disk space and - memory. - - - - A full complement of C, - C++ and Fortran - development tools. Many additional languages for advanced research - and development are also available in the ports and packages - collection. - - - - Source code 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? - - - - Extensive on-line documentation. - - - - And many more! - - - - 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 - now! - - 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. - - 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: - - - - Internet Services: The robust TCP/IP - networking built into FreeBSD makes it an ideal platform for a - variety of Internet services such as: - - - - FTP servers - - - - World Wide Web servers - - - - Gopher servers - - - - Electronic Mail servers - - - - USENET News - - - - Bulletin Board Systems - - - - And more... - - - - You can easily start out small with an inexpensive 386 class PC - and upgrade as your enterprise grows. - - - - Education: 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 other - work done! - - - - Research: 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. - - - - Networking: 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. - - - - X Window workstation: 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. - - - - Software Development: The basic FreeBSD - system comes with a full complement of development tools including - the renowned GNU C/C++ compiler and debugger. - - - - FreeBSD is available in both source and binary form on CDROM and via - anonymous ftp. See Obtaining FreeBSD - for more details. - - - - A Brief History of FreeBSD - - Contributed by &a.jkh;. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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). - - 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. - - 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. - - 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). - - - - FreeBSD Project Goals - - Contributed by &a.jkh;. - - 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. - - 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. - - - - The FreeBSD Development Model - - Contributed by &a.asami;. - - 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 list of contributors. 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 ftp.FreeBSD.org - 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. - - Useful things to know about the FreeBSD project and its development - process, whether working independently or in close cooperation: - - - - The CVS repository - - - The central source tree for FreeBSD is maintained by CVS - (Concurrent Version System), a freely available source code - control tool which comes bundled with FreeBSD. The primary CVS - repository 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 -current and -stable trees which are checked out of - it, can be easily replicated to your own machine as well. Please - refer to the Synchronizing your source - tree section for more information on doing this. - - - - - The committers list - - - The committers are the - people who have write 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; commit 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 committers@FreeBSD.org. - - - - - The FreeBSD core team - - - The FreeBSD core team 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. - - Some core team members also have specific areas of responsibility, meaning that - they are committed to ensuring that some large portion of the - system works as advertised. - - - 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! ;) - - - - - - Outside contributors - - - 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 mailing list info) where such - things are discussed. - - The list 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? :-) - - 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 how to - contribute section in this handbook. - - - - - In summary, our development model is organized as a loose set of - concentric circles. The centralized model is designed for the - convenience of the users 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 application programs that the users can easily - install and use, and this model works very well in accomplishing - that. - - 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! - - - - About the Current Release - - 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. - - 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. - - 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! - - 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 - make all followed by make install - 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. - - 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 - /usr/share/doc 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: - - - - The FreeBSD handbook - - - file:/usr/share/doc/handbook/handbook.html - - - - - The FreeBSD FAQ - - - file:/usr/share/doc/FAQ/FAQ.html - - - - - You can also visit the master (and most frequently updated) - copies at http://www.FreeBSD.org. - - 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 FreeBSD FAQ. - - 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! - - - - - 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 @@ - - - - Configuring the FreeBSD Kernel - - Contributed by &a.jehamby;. 6 October - 1995. - - 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. - - - Why Build a Custom Kernel? - - 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 GENERIC kernel, which must support every - possible SCSI and network card, along with tons of other rarely used - hardware support, a custom kernel only contains support for - your PC's hardware. This has a number of - benefits: - - - - It will take less time to boot because it does not have to spend - time probing for hardware which you do not have. - - - - 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. - - - - 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 - not present in the GENERIC kernel. - - - - - - Building and Installing a Custom Kernel - - First, let us take a quick tour of the kernel build directory. All - directories mentioned will be relative to the main - /usr/src/sys directory, which is also accessible - through /sys. There are a number of subdirectories - here representing different parts of the kernel, but the most important, - for our purposes, are i386/conf, where you will - edit your custom kernel configuration, and compile, - 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 i386 directory deals with PC hardware only, - while everything outside the i386 directory is - common to all platforms which FreeBSD could potentially be ported - to. - - - If there is not a - /usr/src/sys directory on your system, then the - kernel source has not been been installed. The easiest way to do this - is by running /stand/sysinstall as - root, choosing Configure, then - Distributions, then src, then - sys. - - - Next, move to the i386/conf directory and copy - the GENERIC configuration file to the name you want - to give your kernel. For example: - - &prompt.root; cd /usr/src/sys/i386/conf -&prompt.root; cp GENERIC MYKERNEL - - Traditionally, this name is in all capital letters and, if you are - maintaining multiple FreeBSD machines with different hardware, it is a - good idea to name it after your machine's hostname. We will call it - MYKERNEL for the purpose of this example. - - - You must execute these and all of the following commands under the - root account or you will get permission denied - errors. - - - Now, edit MYKERNEL with your favorite text - editor. If you are just starting out, the only editor available will - probably be vi, which is too complex to explain here, - but is covered well in many books in the bibliography. 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 - GENERIC. - - If you have build a kernel under SunOS or some other BSD operating - system, much of this file will be very familiar to you. If you are - coming from some other operating system such as DOS, on the other hand, - the GENERIC configuration file might seem - overwhelming to you, so follow the descriptions in the Configuration File section slowly - and carefully. - - - 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 /usr/src/usr.sbin, so you will - need to download those sources as well. Re-build and install it - before running the next commands. - - - When you are finished, type the following to compile and install - your kernel: - - &prompt.root; /usr/sbin/config MYKERNEL -&prompt.root; cd ../../compile/MYKERNEL -&prompt.root; make depend -&prompt.root; make -&prompt.root; make install - - The new kernel will be copied to the root directory as - /kernel and the old kernel will be moved to - /kernel.old. Now, shutdown the system and reboot - to use your kernel. In case something goes wrong, there are some troubleshooting instructions at - the end of this document. Be sure to read the section which explains how - to recover in case your new kernel does not boot. - - - If you have added any new devices (such as sound cards) you may - have to add some device - nodes to your /dev directory before you - can use them. - - - - - The Configuration File - - 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 - # is considered a comment and ignored. The following - sections describe each keyword, generally in the order they are listed - in GENERIC, although some related keywords have - been grouped together in a single section (such as Networking) even - though they are actually scattered throughout the - GENERIC file. - An exhaustive list of options and - more detailed explanations of the device lines is present in the - LINT configuration file, located in the same - directory as GENERIC. If you are in doubt as to - the purpose or necessity of a line, check first in - LINT. - - 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 switch for the - CFLAGS line of the kernel Makefile. Naturally, this - caused a creeping optionism, with nobody really knowing which option has - been referenced in what files. - - In the new scheme, every #ifdef that is intended - to be dependent upon an option gets this option out of an - opt_foo.h declaration - file created in the compile directory by config. The - list of valid options for config lives in two files: - options that do not depend on the architecture are listed in - /sys/conf/options, architecture-dependent ones in - /sys/arch/conf/options.arch, - with arch being for example - i386. - - - Quoting numbers - - 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. - - Where numbers are used as numbers, as in maxusers - 64, the quotation marks are not - required. - - This requirement was removed in FreeBSD-current (the 4.0 release - candidate). - - The examples here include the quote marks ("). - If you are building a kernel on a -current system you should omit - them. - - - - Mandatory Keywords - - These keywords are required in every kernel you build. - - - - machine arch - - - - The first keyword is machine, which, - since FreeBSD only runs on Intel 386 (and compatible) chips and - DEC Alpha processors, will be either - i386 or - alpha. - - - - - cpu - "cpu_type" - - - The next keyword is cpu, which includes - support for each CPU supported by FreeBSD. The possible values - of cpu_type for i386 systems - include: - - - - I386_CPU - - - - I486_CPU - - - - I586_CPU - - - - I686_CPU - - - - The values available for cpu_type - for Alpha systems include: - - - - EV4 - - - - EV5 - - - - Multiple instances of the cpu line may be - present with different values of - cpu_type as are present in the - GENERIC kernel. For a custom kernel, it is - best to specify only the cpu you have. If, for example, you - have an Intel Pentium, use I586_CPU for - cpu_type. - - - - - ident - machine_name - - - Next, we have ident, which is the - identification of the kernel. You should change this from - GENERIC to whatever you named your kernel, in - this example, MYKERNEL. The value you put in - ident 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 - machine and cpu, enclose - your kernel's name in quotation marks if it contains any - numbers. - - Since this name is passed to the C compiler as a - switch, do not use names like - DEBUG, or something that could be confused - with another machine or CPU name, like - vax. - - - - - maxusers - number - - - 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 - maxusers to at least 4, - especially if you are using the X Window System or compiling - software. The reason is that the most important table set by - maxusers is the maximum number of processes, - which is set to 20 + 16 * maxusers, so if you - set maxusers to 1, 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 - maxusers to 4 will allow - you to have up to 84 simultaneous processes, which should be - enough for anyone. If, however, you see the dreaded - proc table full error when trying to - start another program, or are running a server with a large - number of simultaneous users (like Walnut Creek CDROM's FTP - site), you can always increase this number and rebuild. - - - maxuser does not - 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 does limit - the number of simultaneous remote logins - is pseudo-device pty - 16. - - - - - - config - kernel_name root on - root_device - - - This line specifies the location and name of the kernel. - Traditionally the kernel is called vmunix - but in FreeBSD, it is aptly named kernel. - You should always use kernel for - kernel_name 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 - wd0 for systems with non-SCSI drives, or - da0 for systems with SCSI drives. - - - - - - - General Options - - These lines provide kernel support for various filesystems and - other options. - - - - options MATH_EMULATE - - - 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. - - - The normal math co-processor emulation routines that come - with FreeBSD are not 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 - GPL_MATH_EMULATE to use the superior GNU - math support, which is not included by default for licensing - reasons. - - - - - - options "COMPAT_43" - - - Compatibility with 4.3BSD. Leave this in; some programs - will act strangely if you comment this out. - - - - - options BOUNCE_BUFFERS - - - 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. - - - - - options UCONSOLE - - - Allow users to grab the console, useful for X Windows. For - example, you can create a console xterm by typing xterm - -C, which will display any write, - talk, and other messages you receive, as well - as any console messages sent by the kernel. - - - - - options SYSVSHM - - - 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. - - - - - options SYSVSEM - - - Support for System V semaphores. Less commonly used but - only adds a few hundred bytes to the kernel. - - - - - options SYSVMSG - - - Support for System V messages. Again, only adds a few - hundred bytes to the kernel. - - - The &man.ipcs.1; command will tell will list any processes - using each of these System V facilities. - - - - - - - - Filesystem Options - - 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 FFS if you boot from a hard - drive, or NFS 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 - /modules the first time you mount a partition - of that type. - - - - options FFS - - - The basic hard drive filesystem; leave it in if you boot - from the hard disk. - - - - - options NFS - - - Network Filesystem. Unless you plan to mount partitions - from a Unix file server over Ethernet, you can comment this - out. - - - - - options MSDOSFS - - - 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 - mtools 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). - - - - - options "CD9660" - - - 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. - - - - - options PROCFS - - - Process filesystem. This is a pretend filesystem mounted on - /proc which allows programs like &man.ps.1; - to give you more information on - what processes are running. - - - - - options MFS - - - 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 /tmp - directory, since many programs store temporary data here. To - mount an MFS RAM disk on /tmp, add the - following line to /etc/fstab and then - reboot or type mount /tmp: - - -/dev/wd1s2b /tmp mfs rw 0 0 - - - Replace the /dev/wd1s2b with the name - of your swap partition, which will be listed in your - /etc/fstab as follows: - - -/dev/wd1s2b none swap sw 0 0 - - - - Also, the MFS filesystem can - not be dynamically loaded, so you - must compile it into your kernel if you - want to experiment with it. - - - - - - options "EXT2FS" - - - 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. - - - - - options QUOTA - - - Enable disk quotas. If you have a public access system, and - do not want users to be able to overflow the - /home partition, you can establish disk - quotas for each user. Refer to the Disk - Quotas section for more information. - - - - - - - Basic Controllers and Devices - - These sections describe the basic disk, tape, and CD-ROM - controllers supported by FreeBSD. There are separate sections for - SCSI controllers and network cards. - - - - controller isa0 - - 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. - - - - - controller pci0 - - - Include this if you have a PCI motherboard. This enables - auto-detection of PCI cards and gatewaying from the PCI to the - ISA bus. - - - - - controller fdc0 - - - Floppy drive controller: fd0 is the - A: floppy drive, and - fd1 is the B: drive. - ft0 is a QIC-80 tape drive attached to the - floppy controller. Comment out any lines corresponding to - devices you do not have. - - - QIC-80 tape support requires a separate filter program - called &man.ft.8;, see the manual page for - details. - - - - - - controller wdc0 - - - This is the primary IDE controller. wd0 - and wd1 are the master and slave hard drive, - respectively. wdc1 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). - - - - - device wcd0 - - - This device provides IDE CD-ROM support. Be sure to leave - wdc0 uncommented, and wdc1 - 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 options ATAPI. - - - - - device npx0 at isa? port "IO_NPX" irq 13 - vector npxintr - - - npx0 is the interface to the floating - point math unit in FreeBSD, either the hardware co-processor or - the software math emulator. It is not - optional. - - - - - device wt0 at isa? port 0x300 bio irq 5 drq 1 vector - wtintr - - - Wangtek and Archive QIC-02/QIC-36 tape drive support - - - - - Proprietary CD-ROM support - - - The following drivers are for the so-called - proprietary CD-ROM drives. These drives - have their own controller card or might plug into a sound card - such as the SoundBlaster 16. They are not - IDE or SCSI. Most older single-speed and double-speed CD-ROMs - use these interfaces, while newer quad-speeds are likely to be - IDE or SCSI. - - - - device mcd0 at isa? port 0x300 bio irq 10 - vector mcdintr - - - Mitsumi CD-ROM (LU002, LU005, FX001D). - - - - - device scd0 at isa? port 0x230 - bio - - - Sony CD-ROM (CDU31, CDU33A). - - - - - controller matcd0 at isa? port ? - bio - - - Matsushita/Panasonic CD-ROM (sold by Creative Labs for - SoundBlaster). - - - - - - - - - - SCSI Device Support - - This section describes the various SCSI controllers and devices - supported by FreeBSD. - - - - SCSI Controllers - - - The next ten or so lines include support for different kinds - of SCSI controllers. Comment out all except for the one(s) you - have: - - - - controller bt0 at isa? port "IO_BT0" bio irq ? - vector btintr - - - Most Buslogic controllers - - - - - controller uha0 at isa? port "IO_UHA0" bio irq - ? drq 5 vector uhaintr - - - UltraStor 14F and 34F - - - - - controller ahc0 - - - Adaptec 274x/284x/294x - - - - - controller ahb0 at isa? bio irq ? - vector ahbintr - - - Adaptec 174x - - - - - controller aha0 at isa? port "IO_AHA0" bio - irq ? drq 5 vector ahaintr - - - Adaptec 154x - - - - - controller aic0 at isa? port - 0x340 bio irq 11 vector aicintr - - - Adaptec 152x and sound cards using Adaptec AIC-6360 - (slow!) - - - - - controller nca0 at isa? port 0x1f88 bio irq - 10 vector ncaintr - - - ProAudioSpectrum cards using NCR 5380 or Trantor - T130 - - - - - controller sea0 at isa? bio irq 5 iomem - 0xc8000 iosiz 0x2000 vector seaintr - - - Seagate ST01/02 8 bit controller (slow!) - - - - - controller wds0 at isa? port 0x350 bio irq - 15 drq 6 vector wdsintr - - - Western Digital WD7000 controller - - - - - controller ncr0 - - - NCR 53C810, 53C815, 53C825, 53C860, 53C875 PCI SCSI - controller - - - This also supports the Diamond FirePort - controller. - - - - - - - - - options SCSI_DELAY=15000 - - - 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. - - - - - controller scbus0 - - - 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. - - - - - device da0 - - - Support for SCSI hard drives. - - - - - device sa0 - - - Support for SCSI tape drives. - - - - - device cd0 - - - Support for SCSI CD-ROM drives. - - Note that the number 0 in the above - entries is slightly misleading: all these devices are - automatically configured as they are found, regardless of how - many of them are hooked up to the SCSI bus(es), and which target - IDs they have. - - If you want to “wire down” specific target IDs - to particular devices, refer to the appropriate section of the - LINT kernel config file. - - - - - - - Console, Bus Mouse, Keyboard, and X Server Support - - 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. - - - - device sc0 at isa? port "IO_KBD" tty irq 1 vector - scintr - - - sc0 is the default console driver, which - resembles an SCO console. Since most full-screen programs - access the console through a terminal database library like - termcap, it should not matter much whether - you use this or vt0, the VT220 compatible - console driver. When you log in, set your TERM - variable to “scoansi” if full-screen programs have - trouble running under this console. - - - - - controller atkbdc0 at isa? port IO_KBD - tty - - - The keyboard controller atkbdc provides - I/O services for the AT keyboard and PS/2 style pointing - devices. This controller is required by the keyboard driver - atkbd and the PS/2 pointing device driver - psm. - - - - - options - "KBD_RESETDELAY=X", options - "KBD_MAXWAIT=Y" - - - The keyboard driver atkbd and the - pointing device driver psm may ask the - atkbdc 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 atkbdc - driver should wait before giving up — the driver - will wait X * - Y 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 X and 5 for - Y. - - - - - options - "KBDIO_DEBUG=N" - - - Sets the debug level to N. - The default value is zero, which suppresses all debugging - output. - - - - - - There can only be one atkbdc device - configured into the system. - - - - - - - device atkbd0 at isa? tty irq 1 - - - The atkbd driver, together with the - atkbdc controller, provides access to the - AT 84 keyboard or the AT enhanced keyboard which is connected - to the AT keyboard controller. - - - - - - device vt0 at isa? port "IO_KBD" tty irq 1 vector - pcrint - - - This is a VT220-compatible console driver, backwards - compatible to VT100/102. It works well on some laptops which - have hardware incompatibilities with sc0. - Also, set your TERM variable to - vt100 or vt220 when you - log in. This driver might also prove useful when connecting to - a large number of different machines over the network, where the - termcap or terminfo - entries for the sc0 device are often - not available — vt100 should be - available on virtually any platform. - - - - options "PCVT_FREEBSD=210" - - - Required with the vt0 console - driver. - - - - - options XSERVER - - - Only applicable with the vt0 - console driver. This includes code required to run the - XFree86 X Window Server under - the vt0 console driver. - - - - - - - - device mse0 at isa? port 0x23c tty irq 5 vector - ms - - - Use this device if you have a Logitech or ATI InPort bus - mouse card. - - - If you have a serial mouse, ignore these two lines, and - instead, make sure the appropriate serial port is enabled - (probably COM1). - - - - - - device psm0 at isa? port "IO_KBD" conflicts tty irq - 12 vector psmintr - - - Use this device if your mouse plugs into the PS/2 mouse - port. - - - - - - - Serial and Parallel Ports - - Nearly all systems have these. If you are attaching a printer to - one of these ports, the Printing - section of the handbook is very useful. If you are using modem, Dialup access provides extensive detail on - serial port configuration for use with such devices. - - - - device sio0 at isa? port "IO_COM1" tty irq 4 vector - siointr - - - sio0 through sio3 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 - 0x*2e8, and since many cheap serial cards do - not fully decode the 16-bit IO address space, they clash with - these cards, making the COM4 port practically - unavailable. - - Each serial port is required to have a unique IRQ (unless - you are using one of the multiport cards where shared interrupts - are supported), so the default IRQs for COM3 and COM4 cannot be - used. - - - - - device lpt0 at isa? port? tty irq 7 vector - lptintr - - - lpt0 through lpt2 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. - - - - - - - Networking - - FreeBSD, as with Unix in general, places a - big 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. - - - - options INET - - - 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. - - - - - Ethernet cards - - - 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): - - - - device cs0 - - - IBM Etherjet and other Crystal Semi CS89x0-based - adapters. - - - - - device de0 - - - Ethernet adapters based on Digital Equipment DC21040, - DC21041 or DC21140 chips - - - - - device fxp0 - - - Intel EtherExpress Pro/100B - - - - - device vx0 - - - 3Com 3C590 and 3C595 (buggy) - - - - - device cx0 at isa? port 0x240 net irq 15 drq 7 - vector cxintr - - - Cronyx/Sigma multiport sync/async (with Cisco or PPP - framing) - - - - - device ed0 at isa? port 0x280 net irq 5 iomem - 0xd8000 vector edintr - - - Western Digital and SMC 80xx and 8216; Novell NE1000 - and NE2000; 3Com 3C503; HP PC Lan Plus (HP27247B and - HP27252A) - - - - - device el0 at isa? port 0x300 net irq 9 vector - elintr - - - 3Com 3C501 (slow!) - - - - - device eg0 at isa? port 0x310 net irq 5 vector - egintr - - - 3Com 3C505 - - - - - device ep0 at isa? port 0x300 net irq 10 vector - epintr - - - 3Com 3C509 (buggy) - - - - - device fe0 at isa? port 0x240 net irq ? vector - feintr - - - Fujitsu MB86960A/MB86965A Ethernet - - - - - device fea0 at isa? net irq ? vector - feaintr - - - DEC DEFEA EISA FDDI adapter - - - - - device ie0 at isa? port 0x360 net irq 7 iomem - 0xd0000 vector ieintr - - - AT&T StarLAN 10 and EN100; 3Com 3C507; unknown - NI5210; Intel EtherExpress 16 - - - - - device le0 at isa? port 0x300 net irq 5 iomem - 0xd0000 vector le_intr - - - Digital Equipment EtherWorks 2 and EtherWorks 3 - (DEPCA, DE100, DE101, DE200, DE201, DE202, DE203, DE204, - DE205, DE422) - - - - - device lnc0 at isa? port 0x300 net irq 10 drq 0 - vector lncintr - - - Lance/PCnet cards (Isolan, Novell NE2100, - NE32-VL) - - - - - device xl0 - - - 3Com Etherlink XL series PCI ethernet controllers - (3C905B and related). - - - - - device ze0 at isa? port 0x300 net irq 5 iomem - 0xd8000 vector zeintr - - - IBM/National Semiconductor PCMCIA ethernet - controller. - - - - - device zp0 at isa? port 0x300 net irq 10 iomem - 0xd8000 vector zpintr - - - 3Com PCMCIA Etherlink III - - - - - - 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. - - - - - - pseudo-device loop - - - loop is the generic loopback device for - TCP/IP. If you telnet or FTP to localhost - (a.k.a. 127.0.0.1) it will come - back at you through this pseudo-device. Mandatory. - - - - - pseudo-device ether - - - ether is only needed if you have an - Ethernet card and includes generic Ethernet protocol - code. - - - - - pseudo-device sl - number - - - sl 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 - number after sl - specifies how many simultaneous SLIP sessions to support. This - handbook has more information on setting up a SLIP client or server. - - - - - pseudo-device ppp - number - - - ppp 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 tun and - offers more flexibility and features such as demand dialing. If - you still want to use this PPP driver, read the kernel-mode PPP section of the handbook. - As with the sl device, - number specifies how many - simultaneous PPP connections to support. - - - - - pseudo-device tun - number - - - tun 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 tun specifies the number of - simultaneous PPP sessions to support. See the user-mode PPP section of the handbook - for more information. - - - - - pseudo-device bpfilter - number - - - 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 number 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. - - - - - - - Sound cards - - This is the first section containing lines that are not in the - GENERIC kernel. To include sound card support, you - will have to copy the appropriate lines from the LINT kernel (which - support for every device) as follows: - - - - - controller snd0 - - - Generic sound driver code. Required for all of the - following sound cards except pca. - - - - - device pas0 at isa? port 0x388 irq 10 drq 6 vector - pasintr - - - ProAudioSpectrum digital audio and MIDI. - - - - - device sb0 at isa? port 0x220 irq 7 conflicts drq 1 - vector sbintr - - - SoundBlaster digital audio. - - - If your SoundBlaster is on a different IRQ (such as 5), - change irq 7 to, for example, irq - 5 and remove the conflicts - keyword. - - - - - - device sbxvi0 at isa? drq 5 - - - SoundBlaster 16 digital 16-bit audio. - - - If your SB16 is on a different 16-bit DMA channel (such as - 6 or 7), change the drq 5 keyword - appropriately. - - - - - - device sbmidi0 at isa? port 0x330 - - - SoundBlaster 16 MIDI interface. If you have a SoundBlaster - 16, you must include this line, or the kernel will not - compile. - - - - - device gus0 at isa? port 0x220 irq 10 drq 1 vector - gusintr - - - Gravis Ultrasound. - - - - - device mss0 at isa? port 0x530 irq 10 drq 1 vector - adintr - - - Microsoft Sound System. - - - - - device opl0 at isa? port 0x388 - conflicts - - - 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 playmidi - (in the ports collection). - - - - - device mpu0 at isa? port 0x330 irq 6 drq - 0 - - - Roland MPU-401 stand-alone card. - - - - - device uart0 at isa? port 0x330 irq 5 vector - "m6850intr" - - - Stand-alone 6850 UART for MIDI. - - - - - device pca0 at isa? port "IO_TIMER1" - tty - - - 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). - - - - - device pcm0 at isa? port ? tty irq 10 drq 1 flags 0x0 - - - - The pcm 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. - - - - - - There is some additional documentation in - /usr/src/sys/i386/isa/sound/. Also, if - you add any of these devices, be sure to create the sound device nodes. - - - - - Pseudo-devices - - 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 network-related - pseudo-devices are in that section, while the remainder are - here. - - - - pseudo-device gzip - - - gzip allows you to run FreeBSD programs - that have been compressed with gzip. The - programs in /stand are compressed so it is - a good idea to have this option in your kernel. - - - The gzip feature currently only works - with a.out binaries. - - - - - - pseudo-device log - - - log is used for logging of kernel error - messages. Mandatory. - - - - - pseudo-device pty - number - - - pty is a “pseudo-terminal” or - simulated login port. It is used by incoming - telnet and rlogin - sessions, xterm, and some other applications such as emacs. The - number indicates the number of - ptys to create. If you need more than - GENERIC default of 16 simultaneous xterm - windows and/or remote logins, be sure to increase this number - accordingly, up to a maximum of 256. - - - - - pseudo-device snp - number - - - 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 - number after snp is the total number - of simultaneous snoop sessions. Optional. - - - - - pseudo-device vn - - - 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. - - - - - pseudo-device ccd - number - - - Concatenated disks. This pseudo-device allows you to - concatenate multiple disk partitions into one large - “meta”-disk. The number - 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. - - - - - - - Joystick, PC Speaker, Miscellaneous - - 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 - every device): - - - - device joy0 at isa? port "IO_GAME" - - - PC joystick device. - - - - - pseudo-device speaker - - - Supports IBM BASIC-style noises through the PC speaker. - Some fun programs which use this are - /usr/sbin/spkrtest, which is a shell script - that plays some simple songs, and - /usr/games/piano which lets you play songs - using the keyboard as a simple piano (this file only exists if - you have installed the games package). Also, - the excellent text role-playing game - NetHack (in the ports collection) can - be configured to use this device to play songs when you play - musical instruments in the game. - - See also the pca0 device. - - - - - - - - Making Device Nodes - - Almost every device in the kernel has a corresponding - “node” entry in the /dev 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 /dev/MAKEDEV, which is executed when you - first install the operating system, creates nearly all of the device - nodes supported. However, it does not create all - of them, so when you add support for a new device, it pays to make sure - that the appropriate entries are in this directory, and if not, add - them. Here is a simple example: - - Suppose you add the IDE CD-ROM support to the kernel. The line to - add is: - - -controller wcd0 - - This means that you should look for some entries that start with - wcd0 in the /dev directory, - possibly followed by a letter, such as c, or preceded - by the letter r, which means a “raw” - device. It turns out that those files are not there, so I must change - to the /dev directory and type: - - &prompt.root; sh MAKEDEV wcd0 - - When this script finishes, you will find that there are now - wcd0c and rwcd0c entries in - /dev so you know that it executed correctly. - - For sound cards, the command: - - &prompt.root; sh MAKEDEV snd0 - - creates the appropriate entries. - - - 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 - /etc/fbtab file. See man - fbtab for more information. - - - Follow this simple procedure for any other - non-GENERIC devices which do not have - entries. - - - All SCSI controllers use the same set of /dev - entries, so you do not need to create these. Also, network cards and - SLIP/PPP pseudo-devices do not have entries in - /dev at all, so you do not have to worry about - these either. - - - - - If Something Goes Wrong - - There are four categories of trouble that can occur when - building a custom kernel. They are: - - - - Config command fails - - - If the config command fails when you give - it your kernel description, you have probably made a simple error - somewhere. Fortunately, config will print the - line number that it had trouble with, so you can quickly skip to - it with vi. For example, if you see: - - config: line 17: syntax error - - you can skip to the problem in vi by typing - 17G in command mode. Make sure the keyword is - typed correctly, by comparing it to the GENERIC kernel or another - reference. - - - - - Make command fails - - - If the make command fails, it usually - signals an error in your kernel description, but not severe enough - for config 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. - - - - - Kernel will not boot - - - If your new kernel does not boot, or fails to recognize your - devices, do not panic! Fortunately, BSD has an excellent mechanism - for recovering from incompatible kernels. Simply type the name of - the kernel you want to boot from (i.e. - kernel.old) at the FreeBSD boot prompt - instead of pressing return. When reconfiguring a kernel, it is - always a good idea to keep a kernel that is known to work on - hand. - - After booting with a good kernel you can check over your - configuration file and try to build it again. One helpful - resource is the /var/log/messages 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. - - - If you are having trouble building a kernel, make sure to - keep a GENERIC, or some other kernel that - is known to work on hand as a different name that will not get - erased on the next build. You cannot rely on - kernel.old because when installing a new - kernel, kernel.old is overwritten with the - last installed kernel which may be non-functional. Also, as - soon as possible, move the working kernel to the proper - kernel location or commands such as - &man.ps.1; will not work properly. The - proper command to “unlock” the kernel file that - make installs (in order to move another - kernel back permanently) is: - - &prompt.root; chflags noschg /kernel - - 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: - - &prompt.root; chflags schg /kernel - - - - - - Kernel works, but ps does not work any - more! - - - 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 - libkvm 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. - - - - - - - - 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 @@ - - - - Kernel Debugging - - Contributed by &a.paul; and &a.joerg; - - - Debugging a Kernel Crash Dump with <command>kgdb</command> - - 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 config kernel 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 dumpdev variable in - /etc/rc.conf. Typically you want to specify one of - the swap devices specified in /etc/fstab. Dumps to - non-swap devices, tapes for example, are currently not supported. Config - your kernel using config -g. See Kernel Configuration for details on - configuring the FreeBSD kernel. - - 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 /etc/rc.conf and /etc/rc. - Alternatively, you can hard-code the dump device via the - dump clause in the config 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. - - - In the following, the term kgdb refers to - gdb run in “kernel debug mode”. This - can be accomplished by either starting the gdb with - the option , or by linking and starting it under - the name kgdb. 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. - - - When the kernel has been built make a copy of it, say - kernel.debug, and then run strip - -g 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. - - 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 flag at the boot prompt, and - then perform the following steps: - - &prompt.root; fsck -p -&prompt.root; mount -a -t ufs # so your file system for /var/crash is writable -&prompt.root; savecore -N /kernel.panicked /var/crash -&prompt.root; exit # ...to multi-user - - 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. - - Now, after a crash dump, go to - /sys/compile/WHATEVER and run - kgdb. From kgdb do: - - symbol-file kernel.debug -exec-file /var/crash/kernel.0 -core-file /var/crash/vmcore.0 - - and voila, you can debug the crash dump using the kernel sources just - like you can for any other program. - - Here is a script log of a kgdb 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. - - 1:Script started on Fri Dec 30 23:15:22 1994 - 2:&prompt.root; cd /sys/compile/URIAH - 3:&prompt.root; kgdb kernel /var/crash/vmcore.1 - 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:(kgdb) where -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:(kgdb) up 10 -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:(kgdb) frame frame->tf_ebp frame->tf_eip -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:(kgdb) list -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:(kgdb) print tp -53:Reading in symbols for ../../i386/i386/cons.c...done. -54:$1 = (struct tty *) 0x1bae -55:(kgdb) print tp->t_line -56:$2 = 1767990816 -57:(kgdb) up -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:(kgdb) up -62:#2 0xf0132c34 in spec_open () -63:(kgdb) up -64:#3 0xf012d014 in vn_open () -65:(kgdb) up -66:#4 0xf012a183 in open () -67:(kgdb) up -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:(kgdb) up -75:Initial frame selected; you cannot go up. -76:(kgdb) quit -77:&prompt.root; exit -78:exit -79: -80:Script done on Fri Dec 30 23:18:04 1994 - Comments to the above script: - - - - line 6: - - - 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. - - - - - line 20: - - - This is the location of function trap() - in the stack trace. - - - - - line 36: - - - 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. - - - - - line 52: - - - The pointer looks suspicious, but happens to be a valid - address. - - - - - line 56: - - - However, it obviously points to garbage, so we have found our - error! (For those unfamiliar with that particular piece of code: - tp->t_line refers to the line discipline of - the console device here, which must be a rather small integer - number.) - - - - - - - Debugging a crash dump with DDD - - Examining a kernel crash dump with a graphical debugger like - ddd is also possible. Add the - option to the ddd command line you would use - normally. For example; - - &prompt.root; ddd -k /var/crash/kernel.0 /var/crash/vmcore.0 - - You should then be able to go about looking at the crash dump using - ddd's graphical interface. - - - - Post-mortem Analysis of a Dump - - What do you do if a kernel dumped core but you did not expect it, - and it is therefore not compiled using config -g? Not - everything is lost here. Do not panic! - - Of course, you still need to enable crash dumps. See above on the - options you have to specify in order to do this. - - Go to your kernel config directory - (/usr/src/sys/arch/conf) - and edit your configuration file. Uncomment (or add, if it does not - exist) the following line - - -makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols - - Rebuild the kernel. Due to the time stamp change on the Makefile, - there will be some other object files rebuild, for example - trap.o. With a bit of luck, the added - 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. - - 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 kgdb - session until you know enough. - - All this is not guaranteed to work, but it will do it fine in most - cases. - - - - On-line Kernel Debugging Using DDB - - While kgdb 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. - - 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 kgdb. - - To configure your kernel to include DDB, add the option line - - -options DDB - - to your config file, and rebuild. (See Kernel Configuration for details on - configuring the FreeBSD kernel. - - - 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.) - - - Once your DDB kernel is running, there are several ways to enter - DDB. The first, and earliest way is to type the boot flag - 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. - - 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 (options BREAK_TO_DEBUGGER - 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. - - 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. - - The DDB commands roughly resemble some gdb - commands. The first thing you probably need to do is to set a - breakpoint: - - b function-name -b address - - Numbers are taken hexadecimal by default, but to make them distinct - from symbol names; hexadecimal numbers starting with the letters - a-f need to be preceded with 0x - (this is optional for other numbers). Simple expressions are allowed, - for example: function-name + 0x103. - - To continue the operation of an interrupted kernel, simply - type: - - c - - To get a stack trace, use: - - trace - - - 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. - - - If you want to remove a breakpoint, use - - - del -del address-expression - - 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: - - show b - - To single-step the kernel, try: - - s - - This will step into functions, but you can make DDB trace them until - the matching return statement is reached by: - - n - - - This is different from gdb's - next statement; it is like gdb's - finish. - - - To examine data from memory, use (for example): - - x/wx 0xf0133fe0,40 -x/hd db_symtab_space -x/bc termbuf,10 -x/s stringbuf - - 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: - - x ,10 - - Similarly, use - - x/ia foofunc,10 - - to disassemble the first 0x10 instructions of - foofunc, and display them along with their offset - from the beginning of foofunc. - - To modify memory, use the write command: - - w/b termbuf 0xa 0xb 0 -w/w 0xf0010030 0 0 - - The command modifier - (b/h/w) - 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. - - If you need to know the current registers, use: - - show reg - - Alternatively, you can display a single register value by e.g. - - p $eax - - and modify it by: - - set $eax new-value - - Should you need to call some kernel functions from DDB, simply - say: - - call func(arg1, arg2, ...) - - The return value will be printed. - - For a &man.ps.1; style summary of all running processes, use: - - ps - - 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: - - call diediedie() - - 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 continue - statement. There is now an alias for this: - panic. - - call boot(0) - - Which might be a good way to cleanly shut down the running system, - sync() 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. - - call cpu_reset() - - is the final way out of disaster and almost the same as hitting the - Big Red Button. - - If you need a short command summary, simply type: - - help - - 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. - - - - On-line Kernel Debugging Using Remote GDB - - This feature has been supported since FreeBSD 2.2, and it is - actually a very neat one. - - GDB has already supported remote debugging 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). - - You should configure the kernel in question with config - -g, include 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 strip -x, and boot it - using the 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: - - &prompt.user; gdb -k kernel -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... -(kgdb) - - Initialize the remote debugging session (assuming the first serial - port is being used) by: - - (kgdb) target remote /dev/cuaa0 - - Now, on the target host (the one that entered DDB right before even - starting the device probe), type: - - Debugger("Boot flags requested debugger") -Stopped at Debugger+0x35: movb $0, edata+0x51bc -db> gdb - - DDB will respond with: - - Next trap will enter GDB remote protocol mode - - Every time you type gdb, the mode will be toggled - between remote GDB and local DDB. In order to force a next trap - immediately, simply type s (step). Your hosting GDB - will now gain control over the target kernel: - - Remote debugging using /dev/cuaa0 -Debugger (msg=0xf01b0383 "Boot flags requested debugger") - at ../../i386/i386/db_interface.c:257 -(kgdb) - - 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. - - Remote GDB can also be used to debug LKMs. First build the LKM with - debugging symbols: - - &prompt.root; cd /usr/src/lkm/linux -&prompt.root; make clean; make COPTS=-g - - Then install this version of the module on the target machine, load - it and use modstat to find out where it was - loaded: - - &prompt.root; linux -&prompt.root; modstat -Type Id Off Loadaddr Size Info Rev Module Name -EXEC 0 4 f5109000 001c f510f010 1 linux_mod - - 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 add-symbol-file command in - GDB to tell the debugger about the module: - - (kgdb) add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020 -add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at -text_addr = 0xf5109020? (y or n) y -(kgdb) - - You now have access to all the symbols in the LKM. - - - - Debugging a Console Driver - - 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 at the Boot: 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. - - - - - 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 @@ - - - - Adding New Kernel Configuration Options - - Contributed by &a.joerg; - - - You should be familiar with the section about kernel configuration before reading - here. - - - - What's a <emphasis>Kernel Option</emphasis>, Anyway? - - The use of kernel options is basically described in the kernel configuration 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 make depend 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. - - 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 .h 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: - - -#ifndef THIS_OPTION -#define THIS_OPTION (some_default_value) -#endif /* THIS_OPTION */ - - 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. - - It is also possible to create value-less options that simply enable - or disable a particular piece of code by embracing it in - - -#ifdef THAT_OPTION - -[your code here] - -#endif - - Simply mentioning THAT_OPTION in the config file - (with or without any value) will then turn on the corresponding piece of - code. - - 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 #ifdef referencing it... - However, it's unlikely that many people would put - - -options notyet,notdef - - in their config file, and then wonder why the kernel compilation - falls over. :-) - - 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 new-style option scheme, where - each option goes into a separate .h file in the - kernel compile directory, which is by convention named - opt_foo.h. This way, - the usual Makefile dependencies could be applied, and - make can determine what needs to be recompiled once - an option has been changed. - - 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 #ifdef 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. - - - - Now What Do I Have to Do for it? - - First, edit sys/conf/options (or - sys/i386/conf/options.<arch>, - e. g. sys/i386/conf/options.i386), and select an - opt_foo.h file where - your new option would best go into. - - 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 - opt_scsi.h. By default, simply mentioning an - option in the appropriate option file, say FOO, - implies its value will go into the corresponding file - opt_foo.h. This can be overridden on the - right-hand side of a rule by specifying another filename. - - If there is no - opt_foo.h already - available for the intended new option, invent a new name. Make it - meaningful, and comment the new section in the - options[.<arch>] - 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.. - - Packing too many options into a single - opt_foo.h will cause too - many kernel files to be rebuilt when one of the options has been changed - in the config file. - - 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, &prompt.user; find /usr/src/sys -name - type f | xargs fgrep NEW_OPTION is your friend - in finding them. Go and edit all those files, and add - #include "opt_foo.h" on top, - before all the #include <xxx.h> stuff. This - sequence is most important as the options could override defaults from - the regular include files, if the defaults are of the form - #ifndef NEW_OPTION #define NEW_OPTION (something) - #endif in the regular header. - - Adding an option that overrides something in a system header file - (i.e., a file sitting in /usr/include/sys/) is - almost always a mistake. - opt_foo.h 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. - - - - - 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 @@ - - - - Localization - - - Russian Language (KOI8-R encoding) - - Contributed by &a.ache; 1 May - 1997. - - See more info about KOI8-R encoding at KOI8-R References - (Russian Net Character Set). - - - Console Setup - - - - Add following line to your kernel configuration file: - - -options "SC_MOUSE_CHAR=0x03" - - to move character codes used for mouse cursor off KOI8-R - pseudographics range. - - - - Russian console entry in - /etc/rc.conf should looks like: - - -keymap=ru.koi8-r -keychange="61 ^[[K" -scrnmap=koi8-r2cp866 -font8x16=cp866b-8x16 -font8x14=cp866-8x14 -font8x8=cp866-8x8 - - - ^[ means that real ESC character must be entered into - /etc/rc.conf, not just ^[ string. - - - This tuning means KOI8-R keyboard with Alternative screen font - mapped to KOI8-R encoding to preserve pseudographics, - Gray Delete key remapped to match Russian - &man.termcap.5; entry for - FreeBSD console. - - RUS/LAT switch will be CapsLock. Old - CapsLock function still available via - Shift+CapsLock. CapsLock LED will indicate RUS - mode, not CapsLock mode. - - - - For each ttyv? entry in - /etc/ttys change terminal type from - cons25 to cons25r, i.e. each - entry should looks like: - - -ttyv0 "/usr/libexec/getty Pc" cons25r on secure - - - - - - Locale Setup - - There is two environment variables - for locale setup: - - - - LANG for POSIX &man.setlocale.3; family - functions; - - - - MM_CHARSET for applications MIME character - set. - - - - The best way is using /etc/login.conf - russian user's login class in - &man.passwd.5; entry login class position. See &man.login.conf.5; - for details. - - - Login Class Method - - First of all check your /etc/login.conf - have russian login class, this entry may looks - like: - - -russian:Russian Users Accounts:\ - :charset=KOI8-R:\ - :lang=ru_RU.KOI8-R:\ - :tc=default: - - - How to do it with &man.vipw.8; - - If you use &man.vipw.8; for adding new users, - /etc/master.passwd entry should looks - like: - - -user:password:1111:11:russian:0:0:User Name:/home/user:/bin/csh - - - - How to do it with &man.adduser.8; - - If you use &man.adduser.8; for adding new users: - - - - Set - - -defaultclass = russian - - in /etc/adduser.conf (you must enter - default class for all non-Russian users in - this case); - - - - Alternative variant will be answering - russian each time when you see - - Enter login class: default []: - prompt from &man.adduser.8;; - - - - Another variant: call - - &prompt.root; adduser -class russian - - for each Russian user you want to add. - - - - - - How to do it with &man.pw.8; - - If you use &man.pw.8; for adding new users, call it in this - form: - - &prompt.root; pw useradd user_name -L russian - - - - - Shell Startup Files Method - - If you don't want to use login - class method for some reasons, just set this two environment variables in the - following shell startup files: - - - - /etc/profile: - - -LANG=ru_RU.KOI8-R; export LANG -MM_CHARSET=KOI8-R; export MM_CHARSET - - - - /etc/csh.login: - - -setenv LANG ru_RU.KOI8-R -setenv MM_CHARSET KOI8-R - - - - Alternatively you can add this instructions to - - - - /usr/share/skel/dot.profile: - - (similar to /etc/profile above); - - - - /usr/share/skel/dot.login: - - (similar to /etc/csh.login - above). - - - - - - - Printer Setup - - 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 - /usr/libexec/lpr/ru/koi2alt. So, Russian printer - /etc/printcap entry should looks like: - - -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: - - See &man.printcap.5; for detailed description. - - - - MSDOS FS and Russian file names - - Look at following example &man.fstab.5; entry to enable support - for Russian file names in MSDOS FS: - - -/dev/sd0s1 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0 - - See &man.mount.msdos.8; for detailed description of - and options. - - - - X Window Setup - - Step by step instructions: - - - - Do non-X locale setup - first as described. - - - Russian KOI8-R locale may not work - with old XFree86 releases (lower than 3.3). XFree86 port from - /usr/ports/x11/XFree86 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). - - - - - Go to /usr/ports/russian/X.language - directory and say - - &prompt.root; make all install - there. This port install latest version of KOI8-R fonts. XFree86 - 3.3 already have some KOI8-R fonts, but this ones scaled - better. - - Check find "Files" section in your - /etc/XF86Config, following lines must be - before any other FontPath entries: - - -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc" -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi" -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi" - - If you use high resolution video mode, swap 75 dpi and 100 dpi - lines. - - - - To activate Russian keyboard add - - -XkbKeymap "xfree86(ru)" - - line into "Keyboard" section in your - /etc/XF86Config, also make sure that - XkbDisable is turned off (commented out) - there. - - RUS/LAT switch will be CapsLock. Old - CapsLock function still available via - Shift+CapsLock (in LAT mode only). - - - Russian XKB keyboard may not work with old XFree86 versions, - see locale note for more - info. Russian XKB keyboard may not work with non-localized - applications too, minimally localized application should call - XtSetLanguageProc (NULL, NULL, NULL); - function early in the program. - - - - - - - - German Language (ISO 8859-1) - - Slaven Rezic eserte@cs.tu-berlin.de wrote a tutorial - how to use umlauts on a FreeBSD machine. The tutorial is written in - German and available at http://www.de.FreeBSD.org/de/umlaute/. - - - - - 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 @@ - - - - Linux Emulation - - Contributed by &a.handy; and &a.rich; - - - How to Install the Linux Emulator - - 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. - - There are some Linux-specific operating system features that are not - supported on FreeBSD. Linux binaries will not work on FreeBSD if they - use the Linux /proc filesystem (which is different - from the optional FreeBSD /proc filesystem) or - i386-specific calls, such as enabling virtual 8086 mode. - - Depending on which version of FreeBSD you are running, how you get - Linux-emulation up will vary slightly: - - - Installing Linux Emulation in 2.1-STABLE - - The GENERIC 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). - - To enable the emulator, add the following to your configuration - file (c.f. /sys/i386/conf/LINT): - - -options COMPAT_LINUX - - If you want to run doom or other applications that need shared - memory, also add the following. - - -options SYSVSHM - - The linux system calls require 4.3BSD system call compatibility. - So make sure you have the following. - - -options "COMPAT_43" - - If you prefer to statically link the emulator in the kernel rather - than use the loadable kernel module (LKM), then add - - -options LINUX - - Then run config and install the new kernel as described in the - kernel configuration - section. - - If you decide to use the LKM you must also install the loadable - module. A mismatch of versions between the kernel and loadable module - can cause the kernel to crash, so the safest thing to do is to - reinstall the LKM when you install the kernel. - - &prompt.root; cd /usr/src/lkm/linux -&prompt.root; make all install - - Once you have installed the kernel and the LKM, you can invoke - `linux' as root to load the LKM. - - &prompt.root; linux -Linux emulator installed -Module loaded as ID 0 - - To see whether the LKM is loaded, run - modstat. - - &prompt.user; modstat -Type Id Off Loadaddr Size Info Rev -Module Name EXEC 0 3 f0baf000 0018 f0bb4000 1 linux_emulator - - 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 - /etc/sysconfig - - -linux=YES - - by changing it from NO to YES. FreeBSD 2.1 RELEASE and earlier do not - have such a line and on those you will need to edit - /etc/rc.local to add the following line. - - -linux - - - - Installing Linux Emulation in 2.2.2-RELEASE and later - - It is no longer necessary to specify options - LINUX or options COMPAT_LINUX. Linux - emulation is done with an LKM (“Loadable Kernel Module”) - so it can be installed on the fly without having to reboot. You will - need the following things in your startup files, however: - - - - In /etc/rc.conf, you need the following - line: - - -linux_enable=YES - - - - This, in turn, triggers the following action in - /etc/rc.i386: - - -# Start the Linux binary emulation if requested. -if [ "X${linux_enable}" = X"YES" ]; then echo -n ' - linux'; linux > /dev/null 2>&1 -fi - - - - If you want to verify it is running, modstat will do that: - - &prompt.user; modstat -Type Id Off Loadaddr Size Info Rev Module Name -EXEC 0 4 f09e6000 001c f09ec010 1 linux_mod - - 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 - - -options LINUX - - to your kernel config file. Then run config and install the new - kernel as described in the kernel - configuration section. - - - - Installing Linux Runtime Libraries - - - Installing using the linux_base port - - 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: - - &prompt.root; cd /usr/ports/emulators/linux_base -&prompt.root; make all install - - and you should have a working linux emulator. Legend (and the - mail archives :-) seems to hold that Linux emulation - works best with linux binaries linked against the ZMAGIC libraries; - QMAGIC libraries (such as those used in Slackware V2.0) may tend to - give the Linuxulator heartburn. 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. - - - - Installing libraries manually - - 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, - /compat/linux, for Linux libraries on your - FreeBSD system. Any shared libraries opened by Linux programs run - under FreeBSD will look in this tree first. So, if a Linux program - loads, for example, /lib/libc.so, FreeBSD will - first try to open /compat/linux/lib/libc.so, - and if that does not exist then it will try - /lib/libc.so. Shared libraries should be - installed in the shadow tree /compat/linux/lib - rather than the paths that the Linux ld.so - reports. - - FreeBSD-2.2-RELEASE and later works slightly differently with - respect to /compat/linux: all files, not just - libraries, are searched for from the “shadow root” - /compat/linux. - - Generally, you will need to look for the shared libraries that - Linux binaries depend on only the first few times that you install - a Linux program on your FreeBSD system. After a while, you will - have a sufficient set of Linux shared libraries on your system to be - able to run newly imported Linux binaries without any extra - work. - - - - How to install additional shared libraries - - What if you install the linux_base 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). - - 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 ldd - linuxxdoom: - - &prompt.user; ldd linuxxdoom -libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 -libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 -libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 - - You would need to get all the files from the last column, and - put them under /compat/linux, with the names in - the first column as symbolic links pointing to them. This means you - eventually have these files on your FreeBSD system: - - /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 - - - Note that if you already have a Linux shared library with a - matching major revision number to the first column of the - ldd output, you will not need to copy the file - named in the last column to your system, the one you already have - should work. It is advisable to copy the shared library anyway if - it is a newer version, though. You can remove the old one, as - long as you make the symbolic link point to the new one. So, if - you have these libraries on your system: - - /compat/linux/lib/libc.so.4.6.27 -/compat/linux/lib/libc.so.4 -> libc.so.4.6.27 - - and you find a new binary that claims to require a later - version according to the output of ldd: - - libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 - - If it is only one or two versions out of date in the in the - trailing digit then do not worry about copying - /lib/libc.so.4.6.29 too, because the program - should work fine with the slightly older version. However, if you - like you can decide to replace the libc.so - anyway, and that should leave you with: - - /compat/linux/lib/libc.so.4.6.29 -/compat/linux/lib/libc.so.4 -> libc.so.4.6.29 - - - - The symbolic link mechanism is only - 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. - - - - - Configuring the <filename>ld.so</filename> — for FreeBSD - 2.2-RELEASE and later - - This section applies only to FreeBSD 2.2-RELEASE and later. - Those running 2.1-STABLE should skip this section. - - 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 - /compat/linux tree): - - /compat/linux/lib/ld.so -/compat/linux/etc/ld.so.config - - 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. - - Retrieve the following files (all from the same ftp site to - avoid any version mismatches), and install them under - /compat/linux (i.e. - /foo/bar is installed as - /compat/linux/foo/bar): - - /sbin/ldconfig -/usr/bin/ldd -/lib/libc.so.x.y.z -/lib/ld.so - - ldconfig and ldd do not - necessarily need to be under /compat/linux; you - can install them elsewhere in the system too. Just make sure they - do not conflict with their FreeBSD counterparts. A good idea would - be to install them in /usr/local/bin as - ldconfig-linux and - ldd-linux. - - Create the file - /compat/linux/etc/ld.so.conf, containing the - directories in which the Linux runtime linker should look for shared - libs. It is a plain text file, containing a directory name on each - line. /lib and /usr/lib - are standard, you could add the following: - - -/usr/X11/lib -/usr/local/lib - - When a linux binary opens a library such as - /lib/libc.so the emulator maps the name to - /compat/linux/lib/libc.so internally. All - linux libraries should be installed under /compat/linux (e.g. - /compat/linux/lib/libc.so, - /compat/linux/usr/X11/lib/libX11.so, etc.) in - order for the emulator to find them. - - Those running FreeBSD 2.2-RELEASE should run the Linux ldconfig - program. - - &prompt.root cd /compat/linux/lib -&prompt.root; /compat/linux/sbin/ldconfig - - ldconfig is statically linked, so it does not - need any shared libraries to run. It creates the file - /compat/linux/etc/ld.so.cache which contains - the names of all the shared libraries and should be rerun to - recreate this file whenever you install additional shared - libraries. - - On 2.1-STABLE do not install - /compat/linux/etc/ld.so.cache or run - ldconfig; in 2.1-STABLE the syscalls are - implemented differently and ldconfig is not - needed or used. - - You should now be set up for Linux binaries which only need a - shared libc. You can test this by running the Linux - ldd on itself. Supposing that you have it - installed as ldd-linux, it should produce - something like: - - &prompt.root; ldd-linux `which ldd-linux` -libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 - - This being done, you are ready to install new Linux binaries. - Whenever you install a new Linux program, you should check if it - needs shared libraries, and if so, whether you have them installed - in the /compat/linux tree. To do this, you run - the Linux version ldd on the new program, and - watch its output. ldd (see also the manual page - for &man.ldd.1;) will print a list of shared libraries - that the program depends on, in the form - majorname - (jumpversion) => - fullname. - - If it prints not found instead of - fullname it means that you need an extra - library. The library needed is shown in majorname and will be of - the form - libXXXX.so.N. - You will need to find a - libXXXX.so.N.mm on a - Linux ftp site, and install it on your system. The - XXXX (name) and - N (major revision number) should match; - the minor number(s) mm are less - important, though it is advised to take the most recent - version. - - - - - Installing Linux ELF binaries - - 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; - - &prompt.user; ./my-linux-elf-binary -ELF binary type not known -Abort - - To help the FreeBSD kernel distinguish between a FreeBSD ELF - binary from a Linux binary, use the &man.brandelf.1; utility. - - &prompt.user; brandelf -t Linux my-linux-elf-binary - - 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. - - - - Configuring the host name resolver - - If DNS does not work or you get the messages - - resolv+: "bind" is an invalid keyword resolv+: -"hosts" is an invalid keyword - - then you need to configure a - /compat/linux/etc/host.conf file containing: - - -order hosts, bind -multi on - - where the order here specifies that /etc/hosts is - searched first and DNS is searched second. When - /compat/linux/etc/host.conf is not installed - linux applications find FreeBSD's /etc/host.conf - and complain about the incompatible FreeBSD syntax. You should remove - bind if you have not configured a name-server using - the /etc/resolv.conf file. - - Lastly, those who run 2.1-STABLE need to set an the - RESOLV_HOST_CONF environment variable so that - applications will know how to search the host tables. If you run - FreeBSD 2.2-RELEASE or later, you can skip this. For the - /bin/csh shell use: - - &prompt.user; setenv RESOLV_HOST_CONF /compat/linux/etc/host.conf - - For /bin/sh use: - - &prompt.user; RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF - - - - Finding the necessary files - - - 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. - - - 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: - - - - sunsite.unc.edu:/pub/Linux/distributions - - - - tsx-11.mit.edu:/pub/linux/distributions - - - - Some European mirrors: - - - - ftp.luth.se:/pub/linux/distributions - - - - ftp.demon.co.uk:/pub/unix/linux - - - - src.doc.ic.ac.uk:/packages/linux/distributions - - - - For simplicity, let us concentrate on Slackware here. This - distribution consists of a number of subdirectories, containing - separate packages. Normally, they are controlled by an install - program, but you can retrieve files “by hand” too. First - of all, you will need to look in the contents - subdir of the distribution. You will find a lot of small text files - here describing the contents of the separate packages. The fastest - way to look something up is to retrieve all the files in the contents - subdirectory, and grep through them for the file you need. Here is an - example of a list of files that you might need, and in which - contents-file you will find it by grepping through them: - - - - - - Library - Package - - - - - - ld.so - ldso - - - - ldconfig - ldso - - - - ldd - ldso - - - - libc.so.4 - shlibs - - - - libX11.so.6.0 - xf_lib - - - - libXt.so.6.0 - xf_lib - - - - libX11.so.3 - oldlibs - - - - libXt.so.3 - oldlibs - - - - - - So, in this case, you will need the packages ldso, shlibs, xf_lib - and oldlibs. In each of the contents-files for these packages, look - for a line saying PACKAGE LOCATION, it will tell - you on which “disk” the package is, in our case it will - tell us in which subdirectory we need to look. For our example, we - would find the following locations: - - - - - Package - Location - - - - - - ldso - diska2 - - - - shlibs - diska2 - - - - oldlibs - diskx6 - - - - xf_lib - diskx9 - - - - - - The locations called - “diskXX” refer to the - slakware/XX - subdirectories of the distribution, others may be found in the - contrib subdirectory. In this case, we could now - retrieve the packages we need by retrieving the following files - (relative to the root of the Slackware distribution tree): - - - - slakware/a2/ldso.tgz - - - - slakware/a2/shlibs.tgz - - - - slakware/x6/oldlibs.tgz - - - - slakware/x9/xf_lib.tgz - - - - Extract the files from these gzipped tarfiles in your - /compat/linux directory (possibly omitting or - afterwards removing files you do not need), and you are done. - - See also: - ftp://ftp.FreeBSD.org/pub/FreeBSD/2.0.5-RELEASE/xperimnt/linux-emu/README and /usr/src/sys/i386/ibcs2/README.iBCS2 - - - - - How to Install Mathematica on FreeBSD - - Contributed by &a.rich; and &a.chuck; - - This document shows how to install the Linux binary distribution of - Mathematica 2.2 on FreeBSD 2.1. - - 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. - - 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. - - - Unpacking the Mathematica distribution - - The binaries are currently distributed by Wolfram on CDROM. The - CDROM has about a dozen tar files, each of which is a binary - distribution for one of the supported architectures. The one for - Linux is named LINUX.TAR. You can, for example, - unpack this into /usr/local/Mathematica: - - &prompt.root; cd /usr/local -&prompt.root; mkdir Mathematica -&prompt.root; cd Mathematica -&prompt.root; tar -xvf /cdrom/LINUX.TAR - - - - Obtaining your Mathematica Password - - Before you can run Mathematica you will have to obtain a password - from Wolfram that corresponds to your “machine ID”. - - Once you have installed the linux compatibility runtime libraries - and unpacked the mathematica you can obtain the “machine - ID” by running the program mathinfo in the - Install directory. - - &prompt.root; cd /usr/local/Mathematica/Install -&prompt.root; mathinfo -LINUX: 'ioctl' fd=5, typ=0x89(), num=0x27 not implemented -richc.isdn.bcm.tmc.edu 9845-03452-90255 - - So, for example, the “machine ID” of - richc is 9845-03452-90255. You - can ignore the message about the ioctl that is not implemented. It - 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. - - 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. - - You can do this by invoking: - - &prompt.root; cd /usr/local/Mathematica/Install -&prompt.root; math.install - - 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 - mathpass in this same directory to correct the - info manually. - - 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 math.install program. The - directories we chose to create beforehand and specify to - math.install were: - - - - - - /usr/local/Mathematica/bin - for binaries - - - - /usr/local/Mathematica/man/man1 - for man pages - - - - /usr/local/Mathematica/lib/X11 - for the XKeysymb file - - - - - - You can also tell it to use /tmp/math.record - for the system record file, where it puts logs of sessions. After - this math.install will continue on to unpacking - things and placing everything where it should go. - - The Mathematica Notebook feature is included separately, as the X - Front End, and you have to install it separately. To get the X Front - End stuff correctly installed, cd into the - /usr/local/Mathematica/FrontEnd directory and - execute the xfe.install 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 /usr/local/Mathematica/bin called - mathematica. - - Lastly, you need to modify each of the shell scripts that - Mathematica has installed. At the beginning of every shell script in - /usr/local/Mathematica/bin add the following - line: - - &prompt.user; XKEYSYMDB=/usr/local/Mathematica/lib/X11/XKeysymDB; export XKEYSYMDB - - This tells Mathematica were to find its own - version of the key mapping file XKeysymDB. - Without this you will get pages of error messages about missing - key mappings. - - On 2.1-STABLE you need to add the following as well: - - &prompt.user; RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF - - 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 /etc/host.conf if you - leave this out. - - You might also want to modify your - /etc/manpath.config file to read the new man - directory, and you may need to edit your ~/.cshrc - file to add /usr/local/Mathematica/bin to your - path. - - That is about all it takes. With this you should be able to type - mathematica and get a really slick looking - Mathematica Notebook screen up. Mathematica has included the Motif - user interfaces, but it is compiled in statically, so you do not need - the Motif libraries. Good luck doing this yourself! - - - - Bugs - - The Notebook front end is known to hang sometimes when reading - notebook files with an error messages similar to: - - File .../Untitled-1.mb appears to be broken for OMPR.257.0 - - 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. - - - - Acknowledgments - - 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! :-) - - - - - How does the emulation work? - - This section is based heavily on an e-mail written to the - chat@FreeBSD.org mailing list, written by Terry Lambert - tlambert@primenet.com (Message ID: - <199906020108.SAA07001@usr09.primenet.com>). - - FreeBSD has an abstraction called an “execution class - loader”. This is a wedge into the &man.execve.2; system - call. - - What happens is that FreeBSD has a list of loaders, instead of a - single loader with a fallback to the #! loader for - running any shell interpreters or shell scripts. - - 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. - - 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. - - The assumption was a default of “whatever the current shell - is”. - - Later, a hack was made for &man.sh.1; to examine the first two - characters, and if they were :\n, then it invoked the - &man.csh.1; shell instead (I believe SCO first made this hack, but am - willing to be corrected). - - What FreeBSD does now is go through a list of loaders, with a - generic #! loader that knows about interpreters as - the characters which follow to the next whitespace next to last, - followed by a fallback to /bin/sh. - - 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). - - The ELF loader looks for a specialized brand, - which is a comment section in the ELF image, and which is not present on - SVR4/Solaris ELF binaries. - - For Linux binaries to function, they must be - branded as type Linux; from - &man.brandelf.1;: - - &prompt.root; brandelf -t Linux file - - When this is done, the ELF loader will see the - Linux brand on the file. - - When the ELF loader sees the Linux brand, the - loader replaces a pointer in the proc - structure. All system calls are indexed through this pointer (in a - traditional UNIX system, this would be the sysent[] 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. - - The Linux system call vector contains, among other things, a list of - sysent[] entries whose addresses reside in the kernel - module. - - When a system call is called by the Linux binary, the trap code - dereferences the system call function pointer off the - proc structure, and gets the Linux, not the FreeBSD, - system call entry points. - - In addition, the Linux emulation dynamically - reroots lookups; this is, in effect, what the - union option to FS mounts ( not - the unionfs!) does. First, an attempt is made to lookup the file in the - /compat/linux/original-path - directory, then only if that fails, the lookup is - done in the - /original-path - 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 /compat/linux - directory tree to ensure that the Linux binaries could not tell they - were not running on Linux. - - 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 - glue functions, and Linux binaries get the Linux - glue functions (most older OS's only had their own - glue functions: addresses of functions in a static - global sysent[] structure array, instead of addresses - of functions dereferenced off a dynamically initialized pointer in the - proc structure of the process making the - call). - - 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 - glue 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. - - 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. - - So why is it called “Linux emulation”? To make it hard - to sell FreeBSD! 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”. - - - - - 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 @@ - - - - Electronic Mail - - Contributed by &a.wlloyd;. - - Electronic Mail configuration is the subject of many System Administration books. If you plan - on doing anything beyond setting up one mailhost for your network, you - need industrial strength help. - - 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 - /etc/namedb and man -k named for - more information. - - - Basic Information - - 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. - - - User program - - This is a program like elm, - pine, mail, 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 sendmail - or delivering it over TCP. - - - - Mailhost Server Daemon - - Usually this program is sendmail or - smail running in the background. Turn it off or - change the command line options in /etc/rc.conf - (or, prior to FreeBSD 2.2.2, /etc/sysconfig). It - is best to leave it on, unless you have a specific reason to want it - off. Example: You are building a Firewall. - - You should be aware that sendmail is a - potential weak link in a secure site. Some versions of - sendmail have known security problems. - - sendmail does two jobs. It looks after - delivering and receiving mail. - - If sendmail 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. - - If it is acting as a delivery agent sendmail - will take the message from the local queue and deliver it across the - Internet to another sendmail on the receivers computer. - - - - DNS — Name Service - - The Domain Name System and its daemon named, - 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. - - 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. - - - - POP Servers - - 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. - - - - Get pop software from the Ports collection that can be - found in /usr/ports or packages collection. - This handbook section has a complete reference on the Ports system. - - - - Modify /etc/inetd.conf to load the POP - server. - - - - The pop program will have instructions with it. Read them. - - - - - Configuration - - - Basic - - 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 - /etc/resolv.conf 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: - - - - Run a name server (man -k named) and have - your own domain smallminingco.com - - - - - Get mail delivered to the current DNS name for your host. Ie: - dorm6.ahouse.school.edu - - - - 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 - /etc/services: - - -smtp 25/tcp mail #Simple Mail Transfer - - 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. - - Try this: - - &prompt.root; hostname -newbsdbox.FreeBSD.org -&prompt.root; host newbsdbox.FreeBSD.org -newbsdbox.FreeBSD.org has address 204.216.27.xx - - If that is all that comes out for your machine, mail directory to - root@newbsdbox.FreeBSD.org will work no - problems. - - If instead, you have this: - - &prompt.root; host newbsdbox.FreeBSD.org -newbsdbox.FreeBSD.org has address 204.216.27.xx -newbsdbox.FreeBSD.org mail is handled (pri=10) by freefall.FreeBSD.org - - All mail sent to your host directly will end up on - freefall, under the same username. - - This information is setup in your domain name server. This should - be the same host that is listed as your primary nameserver in - /etc/resolv.conf - - 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. - - The MX entry for freefall.FreeBSD.org - at one time. - - -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 - - freefall has many MX entries. The lowest MX - number gets the mail in the end. The others will queue mail - temporarily, if freefall is busy or down. - - 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. - - dig, nslookup, and - host are your friends. - - - - Mail for your Domain (Network). - - 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 *.smallminingco.com - and divert it to one machine, your “mailhost”. - - The network users on their workstations will most likely pick up - their mail over POP or telnet. - - A user account with the same username should - exist on both machines. Please use adduser to do - this as required. If you set the shell to - /nonexistent the user will not be allowed to - login. - - 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. - - You basically need to add these lines in your DNS server. - - -pc24.smallminingco.com A xxx.xxx.xxx.xxx ; Workstation ip - MX 10 smtp.smallminingco.com ; Your mailhost - - 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. - - 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. - - This feature is used to implement Virtual E-Mail Hosting. - - Example - - 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: - - -foo.bar MX 10 smtp.smalliap.com ; your mailhost - - The A record is not needed if you only want E-Mail for the domain. - IE: Don't expect ping foo.bar to work unless an - Address record for foo.bar exists as well. - - On the mailhost that actually accepts mail for final delivery to a - mailbox, sendmail must be told what hosts it will - be accepting mail for. - - Add pc24.smallminingco.com to - /etc/sendmail.cw (if you are using - FEATURE(use_cw_file)), or add a Cw - myhost.smalliap.com line to - /etc/sendmail.cf - - If you plan on doing anything serious with - sendmail you should install the - sendmail source. The source has plenty of - documentation with it. You will find information on getting - sendmail source from the UUCP information. - - - - Setting up UUCP. - - Stolen from the FAQ. - - 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 - sendmail configuration file. - - Tweaking /etc/sendmail.cf manually is - considered something for purists. Sendmail version 8 comes with a new - approach of generating config files via some m4 - preprocessing, where the actual hand-crafted configuration is on a - higher abstraction level. You should use the configuration files under - /usr/src/usr.sbin/sendmail/cf. - - If you did not install your system with full sources, the - sendmail config stuff has been broken out into a - separate source distribution tarball just for you. Assuming you have - your CD-ROM mounted, do: - - &prompt.root; cd /usr/src -&prompt.root; tar -xvzf /cdrom/dists/src/ssmailcf.aa - - Do not panic, this is only a few hundred kilobytes in size. The - file README in the cf - directory can serve as a basic introduction to m4 - configuration. - - For UUCP delivery, you are best advised to use the - mailertable feature. This constitutes a database - that sendmail can use to base its routing decision - upon. - - First, you have to create your .mc file. The - directory /usr/src/usr.sbin/sendmail/cf/cf is the - home of these files. Look around, there are already a few examples. - Assuming you have named your file foo.mc, all you - need to do in order to convert it into a valid - sendmail.cf is: - - &prompt.root; cd /usr/src/usr.sbin/sendmail/cf/cf -&prompt.root; make foo.cf - - If you don't have a /usr/obj hierarchy, - then: - - &prompt.root; cp foo.cf /etc/sendmail.cf - - Otherwise: - - &prompt.root; cp /usr/obj/`pwd`/foo.cf /etc/sendmail.cf - - A typical .mc file might look like: - - -include(`../m4/cf.m4') -VERSIONID(`Your version number') -OSTYPE(bsd4.4) - -FEATURE(nodns) -FEATURE(nocanonify) -FEATURE(mailertable) - -define(`UUCP_RELAY', your.uucp.relay) -define(`UUCP_MAX_SIZE', 200000) - -MAILER(local) -MAILER(smtp) -MAILER(uucp) - -Cw your.alias.host.name -Cw youruucpnodename.UUCP - - The nodns and nocanonify - features will prevent any usage of the DNS during mail delivery. The - UUCP_RELAY 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. - - Once you have this, you need this file called - /etc/mailertable. A typical example of this - gender again: - - -# -# 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 - - 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 - uucp-neighbor!recipient 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 - uucp-dom: keyword must be valid UUCP neighbors, as - you can verify using the command uuname. - - 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 - mailertable. You always have to execute this - command each time you change your - mailertable. - - Final hint: if you are uncertain whether some particular mail - routing would work, remember the option to - sendmail. It starts sendmail in - “address test mode”; simply enter 0, - 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. - - &prompt.user; sendmail -bt -ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) -Enter <ruleset> <address> -> 0 foo@interface-business.de -rewrite: ruleset 0 input: foo @ interface-business . de -… -rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo < @ interface-business . de - - - - - FAQ - - Migration from FAQ. - - - Why do I have to use the FQDN for hosts on my site? - - You will probably find that the host is actually in a different - domain; for example, if you are in foo.bar.edu and you wish to reach a host called - mumble in the bar.edu domain, you will have to refer to - it by the fully-qualified domain name, mumble.bar.edu, instead of just - mumble. - - Traditionally, this was allowed by BSD BIND resolvers. However the - current version of BIND 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 mumble must either be found as - mumble.foo.bar.edu, or it will be - searched for in the root domain. - - This is different from the previous behavior, where the search - continued across mumble.bar.edu, - and mumble.edu. Have a look at RFC - 1535 for why this was considered bad practice, or even a security - hole. - - As a good workaround, you can place the line - - -search foo.bar.edu bar.edu - - instead of the previous - - -domain foo.bar.edu - - into your /etc/resolv.conf. However, make sure - that the search order does not go beyond the “boundary between - local and public administration”, as RFC 1535 calls it. - - - - Sendmail says <errorname>mail loops back to - myself</errorname> - - This is answered in the sendmail FAQ as follows: - - -* 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. - - The sendmail FAQ is in - /usr/src/usr.sbin/sendmail and is recommended - reading if you want to do any “tweaking” of your mail - setup. - - - - How can I do E-Mail with a dialup PPP host? - - 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. - - There are at least two way to do this. - - The other is to use UUCP. - - The key is to get a Internet site to provide secondary MX services - for your domain. For example: - - -bigco.com. MX 10 bigco.com. - MX 20 smalliap.com. - - Only one host should be specified as the final recipient ( add - Cw bigco.com in - /etc/sendmail.cf on bigco.com). - - When the senders sendmail 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. - sendmail will automatically deliver it to the - secondary MX site, ie your Internet provider. The secondary MX site - will try every (sendmail_flags = "-bd -q15m" in - /etc/rc.conf ) 15 minutes to connect to your host - to deliver the mail to the primary MX site. - - You might want to use something like this as a login - script. - - -#!/bin/sh -# Put me in /usr/local/bin/pppbigco -( sleep 60 ; /usr/sbin/sendmail -q ) & -/usr/sbin/ppp -direct pppbigco - - If you are going to create a separate login script for a user you - could use sendmail -qRbigco.com instead in the - script above. This will force all mail in your queue for bigco.com to - be processed immediately. - - A further refinement of the situation is as follows. - - Message stolen from the freebsd-isp mailing list. - - -> 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". - - - - - - 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 @@ - - -freebsd-advocacy@FreeBSD.org"> - -freebsd-announce@FreeBSD.org"> - -freebsd-bugs@FreeBSD.org"> - -freebsd-chat@FreeBSD.org"> - -freebsd-core@FreeBSD.org"> - -freebsd-current@FreeBSD.org"> - -cvs-all@FreeBSD.org"> - -freebsd-database@FreeBSD.org"> - -freebsd-doc@FreeBSD.org"> - -freebsd-emulation@FreeBSD.org"> - -freebsd-fs@FreeBSD.org"> - -freebsd-hackers@FreeBSD.org"> - -freebsd-hardware@FreeBSD.org"> - -freebsd-isdn@FreeBSD.org"> - -freebsd-isp@FreeBSD.org"> - -freebsd-java@FreeBSD.org"> - -freebsd-jobs@FreeBSD.org"> - -freebsd-mobile@FreeBSD.org"> - -freebsd-mozilla@FreeBSD.org"> - -freebsd-multimedia@FreeBSD.org"> - -freebsd-net@FreeBSD.org"> - -freebsd-newbies@FreeBSD.org"> - -new-bus-arch@bostonradio.org"> - -freebsd-ports@FreeBSD.org"> - -freebsd-questions@FreeBSD.org"> - -freebsd-scsi@FreeBSD.org"> - -freebsd-security@FreeBSD.org"> - -freebsd-security-notifications@FreeBSD.org"> - -freebsd-small@FreeBSD.org"> - -freebsd-smp@FreeBSD.org"> - -freebsd-stable@FreeBSD.org"> - -freebsd-tokenring@FreeBSD.org"> - -majordomo@FreeBSD.org"> - 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 @@ - - - - Obtaining FreeBSD - - - CD-ROM Publishers - - FreeBSD is available on CD-ROM from Walnut Creek CDROM: - -
- Walnut Creek CDROM - 4041 Pike Lane, Suite F - Concord - CA, 94520 - USA - Phone: +1 925 674-0783 - Fax: +1 925 674-0821 - Email: info@cdrom.com - WWW: http://www.cdrom.com/ -
- - - - FTP Sites - - The official sources for FreeBSD are available via anonymous FTP - from: - -
- ftp://ftp.FreeBSD.org/pub/FreeBSD. -
- - The FreeBSD mirror - sites database 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. - - 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. - - Argentina, - Australia, - Brazil, - Canada, - China, - Czech Republic, - Denmark, - Estonia, - Finland, - France, - Germany, - Hong Kong, - Ireland, - Israel, - Japan, - Korea, - Netherlands, - New Zealand, - Poland, - Portugal, - Russia, - Saudi Arabia, - South Africa, - Spain, - Slovak Republic, - Slovenia, - Sweden, - Taiwan, - Thailand, - UK, - Ukraine, - USA. - - - - Argentina - - - In case of problems, please contact the hostmaster - hostmaster@ar.FreeBSD.org for this domain. - - - - ftp://ftp.ar.FreeBSD.org/pub/FreeBSD - - - - - - - Australia - - - In case of problems, please contact the hostmaster - hostmaster@au.FreeBSD.org for this domain. - - - - ftp://ftp.au.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.au.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.au.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp4.au.FreeBSD.org/pub/FreeBSD - - - - - - - Brazil - - - In case of problems, please contact the hostmaster - hostmaster@br.FreeBSD.org for this domain. - - - - ftp://ftp.br.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.br.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.br.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp4.br.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp5.br.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp6.br.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp7.br.FreeBSD.org/pub/FreeBSD - - - - - - - Canada - - - In case of problems, please contact the hostmaster - hostmaster@ca.FreeBSD.org for this domain. - - - - ftp://ftp.ca.FreeBSD.org/pub/FreeBSD - - - - - - - China - - - In case of problems, please contact the hostmaster - phj@cn.FreeBSD.org for this domain. - - - - ftp://ftp.cn.FreeBSD.org/pub/FreeBSD - - - - - - - Czech Republic - - - In case of problems, please contact the hostmaster - hostmaster@cz.FreeBSD.org for this domain. - - - - ftp://ftp.cz.FreeBSD.org Contact: calda@dzungle.ms.mff.cuni.cz - - - ftp://sunsite.mff.cuni.cz/OS/FreeBSD Contact: jj@sunsite.mff.cuni.cz. - - - - - - - Denmark - - - In case of problems, please contact the hostmaster - hostmaster@dk.FreeBSD.org for this domain. - - - - ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD - - - - - - - Estonia - - - In case of problems, please contact the hostmaster - hostmaster@ee.FreeBSD.org for this domain. - - - - ftp://ftp.ee.FreeBSD.org/pub/FreeBSD - - - - - - - Finland - - - In case of problems, please contact the hostmaster - hostmaster@fi.FreeBSD.org for this domain. - - - - ftp://ftp.fi.FreeBSD.org/pub/FreeBSD - - - - - - - France - - - In case of problems, please contact the hostmaster - hostmaster@fr.FreeBSD.org for this domain. - - - - ftp://ftp.fr.FreeBSD.org/pub/FreeBSD - - - - - - ftp://ftp2.fr.FreeBSD.org/pub/FreeBSD - - - - - - ftp://ftp3.fr.FreeBSD.org/pub/FreeBSD - - - - - - - Germany - - - In case of problems, please contact the hostmaster - hostmaster@de.FreeBSD.org for this domain. - - - - ftp://ftp.de.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.de.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.de.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp4.de.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp5.de.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp6.de.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp7.de.FreeBSD.org/pub/FreeBSD - - - - - - - Hong Kong - - - - - - ftp://ftp.hk.super.net/pub/FreeBSD Contact: ftp-admin@HK.Super.NET. - - - - - - - Ireland - - - In case of problems, please contact the hostmaster - hostmaster@ie.FreeBSD.org for this domain. - - - - ftp://ftp.ie.FreeBSD.org/pub/FreeBSD - - - - - - - Israel - - - In case of problems, please contact the hostmaster - hostmaster@il.FreeBSD.org for this domain. - - - - ftp://ftp.il.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.il.FreeBSD.org/pub/FreeBSD - - - - - - - Japan - - - In case of problems, please contact the hostmaster - hostmaster@jp.FreeBSD.org for this domain. - - - - ftp://ftp.jp.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.jp.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.jp.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp4.jp.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp5.jp.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp6.jp.FreeBSD.org/pub/FreeBSD - - - - - - - Korea - - - In case of problems, please contact the hostmaster - hostmaster@kr.FreeBSD.org for this domain. - - - - ftp://ftp.kr.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.kr.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.kr.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp4.kr.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp5.kr.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp6.kr.FreeBSD.org/pub/FreeBSD - - - - - - - Netherlands - - - In case of problems, please contact the hostmaster - hostmaster@nl.FreeBSD.org for this domain. - - - - ftp://ftp.nl.FreeBSD.org/pub/FreeBSD - - - - - - - New Zealand - - - In case of problems, please contact the hostmaster - hostmaster@nz.FreeBSD.org for this domain. - - - - ftp://ftp.nz.FreeBSD.org/pub/FreeBSD - - - - - - - Poland - - - In case of problems, please contact the hostmaster - hostmaster@pl.FreeBSD.org for this domain. - - - - ftp://ftp.pl.FreeBSD.org/pub/FreeBSD - - - - - - - Portugal - - - In case of problems, please contact the hostmaster - hostmaster@pt.FreeBSD.org for this domain. - - - - ftp://ftp.pt.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.pt.FreeBSD.org/pub/FreeBSD - - - - - - - Russia - - - In case of problems, please contact the hostmaster - hostmaster@ru.FreeBSD.org for this domain. - - - - ftp://ftp.ru.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.ru.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.ru.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp4.ru.FreeBSD.org/pub/FreeBSD - - - - - - - Saudi Arabia - - In case of problems, please contact - ftpadmin@isu.net.sa - - - - ftp://ftp.isu.net.sa/pub/mirrors/ftp.freebsd.org - - - - - - - - South Africa - - - In case of problems, please contact the hostmaster - hostmaster@za.FreeBSD.org for this domain. - - - - ftp://ftp.za.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.za.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.za.FreeBSD.org/pub/FreeBSD - - - - - - - Slovak Republic - - - In case of problems, please contact the hostmaster - hostmaster@sk.FreeBSD.org for this domain. - - - - ftp://ftp.sk.FreeBSD.org/pub/FreeBSD - - - - - - Slovenia - - - In case of problems, please contact the hostmaster - hostmaster@si.FreeBSD.org for this domain. - - - - ftp://ftp.si.FreeBSD.org/pub/FreeBSD - - - - - - - Spain - - - In case of problems, please contact the hostmaster - hostmaster@es.FreeBSD.org for this domain. - - - - ftp://ftp.es.FreeBSD.org/pub/FreeBSD - - - - - - - Sweden - - - In case of problems, please contact the hostmaster - hostmaster@se.FreeBSD.org for this domain. - - - - ftp://ftp.se.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.se.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.se.FreeBSD.org/pub/FreeBSD - - - - - - - Taiwan - - - In case of problems, please contact the hostmaster - hostmaster@tw.FreeBSD.org for this domain. - - - - ftp://ftp.tw.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.tw.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.tw.FreeBSD.org/pub/FreeBSD - - - - - - - Thailand - - - - - ftp://ftp.nectec.or.th/pub/FreeBSD Contact: ftpadmin@ftp.nectec.or.th. - - - - - - - Ukraine - - - - - ftp://ftp.ua.FreeBSD.org/pub/FreeBSD Contact: freebsd-mnt@lucky.net. - - - - - - - UK - - - In case of problems, please contact the hostmaster - hostmaster@uk.FreeBSD.org for this domain. - - - - ftp://ftp.uk.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.uk.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.uk.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp4.uk.FreeBSD.org/pub/FreeBSD - - - - - - - USA - - - In case of problems, please contact the hostmaster - hostmaster@FreeBSD.org for this domain. - - - - ftp://ftp.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp3.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp4.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp5.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp6.FreeBSD.org/pub/FreeBSD - - - - - - - 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: - - - - South Africa - - - Hostmaster hostmaster@internat.FreeBSD.org for - this domain. - - - - ftp://ftp.internat.FreeBSD.org/pub/FreeBSD - - - - ftp://ftp2.internat.FreeBSD.org/pub/FreeBSD - - - - - - - Brazil - - - Hostmaster hostmaster@br.FreeBSD.org for this - domain. - - - - ftp://ftp.br.FreeBSD.org/pub/FreeBSD - - - - - - - Finland - - - - - ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt Contact: count@nic.funet.fi. - - - - - - - - - CTM Sites - - CTM/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. - - In case of problems, please contact &a.phk;. - - - - California, Bay Area, official source - - - - - ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM - - - - - - - Germany, Trier - - - - - ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM - - - - - - - South Africa, backup server for old deltas - - - - - ftp://ftp.internat.FreeBSD.org/pub/FreeBSD/CTM - - - - - - - Taiwan/R.O.C, Chiayi - - - - - ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/CTM - - - - ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/CTM - - - - ftp://ctm3.tw.FreeBSD.org/pub/freebsd/CTM - - - - - - - If you did not find a mirror near to you or the mirror is - incomplete, try FTP - search at http://ftpsearch.ntnu.no/ftpsearch. - FTP search is a great free archie server in Trondheim, Norway. - - - - CVSup Sites - - CVSup servers for FreeBSD are running - at the following sites: - - - - Argentina - - - - - - cvsup.ar.FreeBSD.org (maintainer - msagre@cactus.fi.uba.ar) - - - - - - - Australia - - - - - cvsup.au.FreeBSD.org (maintainer - dawes@physics.usyd.edu.au) - - - - - - - Brazil - - - - - cvsup.br.FreeBSD.org (maintainer - cvsup@cvsup.br.FreeBSD.org) - - - - cvsup2.br.FreeBSD.org (maintainer - tps@ti.sk) - - - - - - - Canada - - - - - cvsup.ca.FreeBSD.org (maintainer - dan@jaded.net) - - - - - - - China - - - - - cvsup.cn.FreeBSD.org (maintainer - phj@cn.FreeBSD.org) - - - - - - - Czech Republic - - - - - cvsup.cz.FreeBSD.org (maintainer - cejkar@dcse.fee.vutbr.cz) - - - - - - - Denmark - - - - - cvsup.dk.FreeBSD.org (maintainer - jesper@skriver.dk) - - - - - - - Estonia - - - - - cvsup.ee.FreeBSD.org (maintainer - taavi@uninet.ee) - - - - - - - Finland - - - - - cvsup.fi.FreeBSD.org (maintainer - count@key.sms.fi) - - - - cvsip2.fi.FreeBSD.org (maintainer - count@key.sms.fi) - - - - - - - France - - - - - cvsup.fr.FreeBSD.org (maintainer - hostmaster@fr.FreeBSD.org) - - - - - - - Germany - - - - - cvsup.de.FreeBSD.org (maintainer - wosch@FreeBSD.org) - - - - cvsup2.de.FreeBSD.org (maintainer - petzi@FreeBSD.org) - - - - cvsup3.de.FreeBSD.org (maintainer - ag@leo.org) - - - - - - - Iceland - - - - - cvsup.is.FreeBSD.org (maintainer - adam@veda.is) - - - - - - - Japan - - - - - - cvsup.jp.FreeBSD.org (maintainer - simokawa@sat.t.u-tokyo.ac.jp) - - - - cvsup2.jp.FreeBSD.org (maintainer - max@FreeBSD.org) - - - - cvsup3.jp.FreeBSD.org (maintainer - shige@cin.nihon-u.ac.jp) - - - - cvsup4.jp.FreeBSD.org (maintainer - cvsup-admin@ftp.media.kyoto-u.ac.jp) - - - - cvsup5.jp.FreeBSD.org (maintainer - cvsup@imasy.or.jp) - - - - - - - Korea - - - - - - cvsup.kr.FreeBSD.org (maintainer - cjh@kr.FreeBSD.org) - - - - - - - Netherlands - - - - - - cvsup.nl.FreeBSD.org (maintainer - xaa@xaa.iae.nl) - - - - - - - Norway - - - - - cvsup.no.FreeBSD.org (maintainer - Tor.Egge@idt.ntnu.no) - - - - - - - Poland - - - - - cvsup.pl.FreeBSD.org (maintainer - Mariusz@kam.pl) - - - - - - - Russia - - - - - cvsup.ru.FreeBSD.org (maintainer - mishania@demos.su) - - - - cvsup2.ru.FreeBSD.org (maintainer - dv@dv.ru) - - - - - - - Spain - - - - - cvsup.es.FreeBSD.org (maintainer - jesusr@FreeBSD.org) - - - - - - - Sweden - - - - - cvsup.se.FreeBSD.org (maintainer - pantzer@ludd.luth.se) - - - - - - - Slovak Republic - - - - - cvsup.sk.FreeBSD.org (maintainer - tps@tps.sk) - - - - cvsup2.sk.FreeBSD.org (maintainer - tps@tps.sk) - - - - - - - South Africa - - - - - cvsup.za.FreeBSD.org (maintainer - markm@FreeBSD.org) - - - - cvsup2.za.FreeBSD.org (maintainer - markm@FreeBSD.org) - - - - - - - Taiwan - - - - - cvsup.tw.FreeBSD.org (maintainer - jdli@freebsd.csie.nctu.edu.tw) - - - - - - - - Ukraine - - - - - - cvsup2.ua.FreeBSD.org (maintainer - freebsd-mnt@lucky.net) - - - - - - - United Kingdom - - - - - cvsup.uk.FreeBSD.org (maintainer - joe@pavilion.net) - - - - cvsup2.uk.FreeBSD.org (maintainer - brian@FreeBSD.org) - - - - - - - USA - - - - - cvsup1.FreeBSD.org (maintainer - skynyrd@opus.cts.cwu.edu), Washington - state - - - - cvsup2.FreeBSD.org (maintainer - jdp@FreeBSD.org), California - - - - cvsup3.FreeBSD.org (maintainer - wollman@FreeBSD.org), Massachusetts - - - - cvsup5.FreeBSD.org (maintainer - ck@adsu.bellsouth.com), Georgia - - - - cvsup6.FreeBSD.org (maintainer - jdp@FreeBSD.org), Florida - - - - - - - The export-restricted code for FreeBSD (eBones and secure) is - available via CVSup at the following - international repository. Please use this site to get the - export-restricted code, if you are outside the USA or Canada. - - - - South Africa - - - - - cvsup.internat.FreeBSD.org (maintainer - markm@FreeBSD.org) - - - - - - - The following CVSup site is especially - designed for CTM users. Unlike the other - CVSup mirrors, it is kept up-to-date by CTM. - That means if you CVSup - cvs-all with release=cvs from this - site, you get a version of the repository (including the inevitable - .ctm_status file) which is suitable for being - updated using the CTM - cvs-cur deltas. This allows users who track the - entire cvs-all tree to go from - CVSup to CTM - without having to rebuild their repository from scratch using a fresh - CTM base delta. - - - This special feature only works for the cvs-all - distribution with cvs as the release tag. - CVSupping any other distribution and/or release will get you the - specified distribution, but it will not be suitable for - CTM updating. - - - - Because the current version of CTM 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. - - - - - Germany - - - - - ctm.FreeBSD.org (maintainer - blank@fox.uni-trier.de) - - - - - - - - - AFS Sites - - AFS servers for FreeBSD are running at the following sites; - - - - Sweden - - - The path to the files are: - /afs/stacken.kth.se/ftp/pub/FreeBSD - - -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 - - Maintainer ftp@stacken.kth.se - - - - - - - - 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 @@ - - -comp.unix.bsd.freebsd.misc - 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 @@ - - - - PGP keys - - 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. - - - Officers - - - FreeBSD Security Officer - <email>security-officer@FreeBSD.org</email> - - -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----- - - - - &a.imp; - - -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----- - - - - - Core Team members - - - &a.asami; - - -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----- - - - - &a.jmb; - - -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----- - - - - &a.ache; - - -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----- - - - - &a.jkh; - - -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----- - - - - &a.phk; - - -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----- - - - - &a.rich; - - -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----- - - - - &a.jdp; - - -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----- - - - - &a.guido; - - -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----- - - - - &a.peter; - - -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----- - - - - &a.joerg; - - -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----- - - - - - Developers - - - &a.wosch; - - -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----- - - - - &a.brian; - - -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----- - - - - - - 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 @@ - - - - Source Tree Guidelines and Policies - - Contributed by &a.phk;. - - This chapter documents various guidelines and policies in force for - the FreeBSD source tree. - - - <makevar>MAINTAINER</makevar> on Makefiles - - June 1996. - - 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 - - -MAINTAINER= email-addresses - - line to the Makefiles covering this portion of the - source tree. - - The semantics of this are as follows: - - 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. - - 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. - - 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. - - - - Contributed Software - - Contributed by &a.phk; and &a.obrien;. - - June 1996. - - Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this contributed software. Some - examples are perl, gcc and patch. - - 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. - - 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. - - 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. - - - 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 strongly discouraged 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. - - - The Tcl embedded programming - language will be used as example of how this model works: - - src/contrib/tcl 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 - mac, win and - compat subdirectories were eliminated before the - import - - src/lib/libtcl contains only a "bmake style" - Makefile that uses the standard - bsd.lib.mk makefile rules to produce the library - and install the documentation. - - src/usr.bin/tclsh contains only a bmake style - Makefile which will produce and install the - tclsh program and its associated man-pages using the - standard bsd.prog.mk rules. - - src/tools/tools/tcl_bmake 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. - - The important thing here is that the - src/contrib/tcl 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. - - 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. - - 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 not be removed. - - If it seems easier, the bmake - Makefiles 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 - src/tools directory along with the port itself so - that it is available to future maintainers. - - In the src/contrib/tcl level directory, a file - called FREEBSD-upgrade should be added and it - should states things like: - - - - Which files have been left out - - - - Where the original distribution was obtained from and/or the - official master site. - - - - Where to send patches back to the original authors - - - - Perhaps an overview of the FreeBSD-specific changes that have - been made. - - - - However, please do not import FREEBSD-upgrade - with the contributed source. Rather you should cvs add - FREEBSD-upgrade ; cvs ci after the initial import. Example - wording from src/contrib/cpio is below: - - -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 - - - - Encumbered files - - 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. - - - - Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered. - - - - Any file with a license more restrictive than BSD or GNU is - encumbered. - - - - 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). - - - - Any encumbered file requires specific approval from the Core team before it is added to the - CVS repository. - - - - Encumbered files go in src/contrib or - src/sys/contrib. - - - - The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code. - - - - Object files are named - arch/filename.o.uu>. - - - - Kernel files; - - - - Should always be referenced in - conf/files.* (for build simplicity). - - - - Should always be in LINT, but the Core team decides per case if it - should be commented out or not. The Core team can, of course, change - their minds later on. - - - - The Release Engineer - decides whether or not it goes in to the release. - - - - - - User-land files; - - - - The Core team decides if - the code should be part of make world. - - - - The Release Engineer - decides if it goes in to the release. - - - - - - - - Shared Libraries - - Contributed by &a.asami;, &a.peter;, and &a.obrien; 9 - December 1996. - - 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. - - The three principles of shared library building are: - - - - Start from 1.0 - - - - If there is a change that is backwards compatible, bump minor - number - - - - If there is an incompatible change, bump major number - - - - 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. - - Stick to version numbers of the form major.minor - (x.y). Our - dynamic linker does not handle version numbers of the form - x.y.z - well. Any version number after the y - (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, - ld.so will link with the higher one. Ie: if you link - with libfoo.so.3.3.3, the linker only records - 3.3 in the headers, and will link with anything - starting with - libfoo.so.3.(anything >= - 3).(highest - available). - - - ld.so will always use the highest - “minor” revision. Ie: it will use - libc.so.2.2 in preference to - libc.so.2.0, even if the program was initially - linked with libc.so.2.0. - - - 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 Makefile'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 Makefile to be updated, and any subsequent - changes will not. - - - - - 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 @@ - - - - Installing Applications: The Ports collection - - Contributed by &a.jraynard;. - - The FreeBSD Ports collection allows you to compile and install a very - wide range of applications with a minimum of effort. - - 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... - - 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 (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?). - - Fortunately, with the Ports collection, all the hard work involved has - already been done, and you can just type make install - and get a working program. - - - Why Have a Ports Collection? - - 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:- - - - - Programs that some people cannot live without and other people - cannot stand, such as a certain Lisp-based editor. - - - - Programs which are too specialised to put in the base system - (CAD, databases). - - - - 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). - - - - Programs that are far too much fun to be supplied with a serious - operating system like FreeBSD ;-) - - - - 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). - - - - 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. - - 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. - - - - How Does the Ports Collection Work? - - Programs are typically distributed on the Internet as a tarball 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. - - 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 make program to compile and install the - program from the source. - - FreeBSD ports still use the tarball mechanism, but use a skeleton 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 Makefile, so that almost every port - can be built in the same way. - - If you look at a port skeleton (either on your FreeBSD - system or the - FTP site) 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 Getting a port). - - “How on earth can this do anything?” I hear you cry. - “There is no source code there!” - - Fear not, gentle reader, all will become clear (hopefully). Let us - see what happens if we try and install a port. I have chosen - ElectricFence, a useful tool for developers, - as the skeleton is more straightforward than most. - - - If you are trying this at home, you will need to be root. - - - &prompt.root; cd /usr/ports/devel/ElectricFence -&prompt.root; make install ->> 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 - - To avoid confusing the issue, I have completely removed the build - output. - - If you tried this yourself, you may well have got something like - this at the start:- - - &prompt.root; make install ->> 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/. - - The make 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. - - Let's go through this and see what the make - program was doing. - - - - Locate the source code tarball. If it is not available - locally, try to grab it from an FTP site. - - - - Run a checksum 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. - - - - Extract the tarball into a temporary work directory. - - - - Apply any patches needed to - get the source to compile and run under FreeBSD. - - - - Run any configuration script required by the build process and - correctly answer any questions it asks. - - - - (Finally!) Compile the code. - - - - Install the program executable and other supporting files, man - pages, etc. under the /usr/local hierarchy - (unless this is an X11 program, - then it will be under /usr/X11R6), - 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. - - - - Register the installation in a database. This means that, if - you do not like the program, you can cleanly remove all traces of it from your - system. - - - - Scroll up to the make output and see if you can - match these steps to it. And if you were not impressed before, you - should be by now! - - - - Getting a FreeBSD Port - - There are two ways of getting hold of the FreeBSD port for a - program. One requires a FreeBSD CDROM, - the other involves using an Internet - Connection. - - - Compiling ports from CDROM - - Assuming that your FreeBSD CDROM is in the drive and mounted on - /cdrom (and the mount point - must be /cdrom), 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 - /cdrom/ports/distfiles/ (if they exist there) - rather than downloading them over the net. - - Another way of doing this, if you want to just use the port - skeletons on the CDROM, is to set these variables in - /etc/make.conf: - - -PORTSDIR= /cdrom/ports -DISTDIR= /tmp/distfiles -WRKDIRPREFIX= /tmp - - Substitute /tmp for any place you have enough - free space. Then, just cd to the appropriate - subdirectory under /cdrom/ports and type - make install as usual. - WRKDIRPREFIX will cause the port to be build under - /tmp/cdrom/ports; for instance, - games/oneko will be built under - /tmp/cdrom/ports/games/oneko. - - - 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 Compiling ports using an Internet - connection. - - - - - Compiling ports from the Internet - - 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 skeleton for the port. Now - this might sound like rather a fiddly job full of pitfalls, but it is - actually very easy. - - First, if you are running a release version of FreeBSD, make sure - you get the appropriate “upgrade kit” for your release - from the ports web - page. These packages include files that have been updated - since the release that you may need to compile new ports. - - The key to the skeletons is that the FreeBSD FTP server can create - on-the-fly tarballs 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!):- - - &prompt.root; cd /usr/ports -&prompt.root; mkdir databases -&prompt.root; cd databases -&prompt.root; ftp ftp.FreeBSD.org -[log in as `ftp' and give your email address when asked for a -password. Remember to use binary (also known as image) mode!] -ftp> cd /pub/FreeBSD/ports/ports/databases -ftp> get gnats.tar -[tars up the gnats skeleton for us] -ftp> quit -&prompt.root; tar xf gnats.tar -[extract the gnats skeleton] -&prompt.root; cd gnats -&prompt.root; make install -[build and install gnats] - - What happened here? We connected to the FTP server in the usual - way and went to its databases sub-directory. - When we gave it the command get gnats.tar, the FTP - server tarred up the gnats - directory for us. - - We then extracted the gnats skeleton and went into the gnats - directory to build the port. As we explained earlier, the make process noticed we - did not have a copy of the source locally, so it fetched one before - extracting, patching and building it. - - 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:- - - &prompt.root; cd /usr/ports -&prompt.root; ftp ftp.FreeBSD.org -[log in as `ftp' and give your email address when asked for a -password. Remember to use binary (also known as image) mode!] -ftp> cd /pub/FreeBSD/ports/ports -ftp> get databases.tar -[tars up the databases directory for us] -ftp> quit -&prompt.root; tar xf databases.tar -[extract all the database skeletons] -&prompt.root; cd databases -&prompt.root; make install -[build and install all the database ports] - - 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? - - If you expect to be installing many ports, it is probably worth - downloading all the ports directories. - - - - - Skeletons - - 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. - - - <filename>Makefile</filename> - - 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:- - - -# 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> - - The lines beginning with a "#" sign are comments for the - benefit of human readers (as in most Unix script files). - - DISTNAME specifies the name of the tarball, but without the - extension. - - CATEGORIES states what kind of program this is. - In this case, a utility for developers. See the categories section of this - handbook for a complete list. - - MASTER_SITES is the URL(s) of the master FTP - site, which is used to retrieve the tarball 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). - - MAINTAINER 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. - - Skipping over the next few lines for a minute, the line - .include <bsd.port.mk> says that the other - statements and commands needed for this port are in a standard file - called bsd.port.mk. 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. - - 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 - MAN3 ensures that the ElectricFence man page is - compressed after installation, to help conserve your precious disk - space. The original port did not provide an - install target, so the three lines from - do-install ensure that the files produced by - this port are placed in the correct destination. - - - - The <filename>files</filename> directory - - The file containing the checksum for the port is called - md5, after the MD5 algorithm used for ports - checksums. It lives in a directory with the slightly confusing name - of files. - - This directory can also contain other miscellaneous files that are - required by the port and do not belong anywhere else. - - - - The <filename>patches</filename> directory - - This directory contains the patches needed to make everything work - properly under FreeBSD. - - - - The <filename>pkg</filename> directory - - This program contains three quite useful files:- - - - - COMMENT — a one-line description of - the program. - - - - DESCR — a more detailed - description. - - - - PLIST — a list of all the files - that will be created when the program is installed. - - - - - - - What to do when a port does not work. - - Oh. You can do one of four (4) things : - - - - Fix it yourself. Technical details on how ports work can be - found in Porting applications. - - - - Gripe. This is done by e-mail only! Send - such e-mail to the maintainer of the port, first. Type - make maintainer or read the - Makefile to find the maintainer's email - address. Remember to include the name/version of - the port (copy the $Id: line from the - Makefile), 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 send-pr. - - - - - Forget it. This is the easiest for most — very few of the - programs in ports can be classified as essential! - - - - Grab the pre-compiled package from a ftp server. The - “master” package collection is on FreeBSD's FTP server - in the packages - directory, 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. - - - - - - Some Questions and Answers - - - - Q. I thought this was going to be a discussion about - modems??! - - 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). - - - - Q. I thought you were supposed to use packages to install extra - programs? - - A. Yes, that is usually the quickest and easiest way of doing - it. - - - - Q. So why bother with ports then? - - A. Several reasons:- - - - - The licensing conditions on some software distributions - require that they be distributed as source code, not - binaries. - - - - 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. - - - - If you have some local patches, you will need the source to - add them yourself. - - - - 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. - - - - 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. - - - - If you ain't got the source, it ain't software! ;-) - - - - - - Q. What is a patch? - - 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. - - - - Q. What is all this about - tarballs? - - A. It is a file ending in .tar or - .tar.gz (with variations like - .tar.Z, or even .tgz if - you are trying to squeeze the names into a DOS filesystem). - - Basically, it is a directory tree that has been archived into a - single file (.tar) and optionally compressed - (.gz). This technique was originally used for - Tape ARchives (hence the - name tar), but it is a widely used way of - distributing program source code around the Internet. - - 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:- - - &prompt.user; tar tvzf foobar.tar.gz -&prompt.user; tar xzvf foobar.tar.gz -&prompt.user; tar tvf foobar.tar -&prompt.user; tar xvf foobar.tar - - - - Q. And a checksum? - - 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). - - - - Q. I did what you said for compiling - ports from a CDROM and it worked great until I tried to - install the kermit port:- - - &prompt.root; make install ->> cku190.tar.gz doesn't seem to exist on this system. ->> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/. - - Why can it not be found? Have I got a dud CDROM? - - 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). - - - - Q. I did that, but when I tried to put it into - /usr/ports/distfiles I got some error about not - having permission. - - A. The ports mechanism looks for the tarball in - /usr/ports/distfiles, 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 - - &prompt.root; make DISTDIR=/where/you/put/it install - - - - Q. Does the ports scheme only work if you have everything in - /usr/ports? My system administrator says I must - put everything under - /u/people/guests/wurzburger, but it does not - seem to work. - - A. You can use the PORTSDIR and - PREFIX variables to tell the ports mechanism to - use different directories. For instance, - - &prompt.root; make PORTSDIR=/u/people/guests/wurzburger/ports install - - will compile the port in - /u/people/guests/wurzburger/ports and install - everything under /usr/local. - - &prompt.root; make PREFIX=/u/people/guests/wurzburger/local install - - will compile it in /usr/ports and install - it in /u/people/guests/wurzburger/local. - - And of course - - &prompt.root; make PORTSDIR=.../ports PREFIX=.../local install - - 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). - - 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. - - - - 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? - - A. To get every single tarball for the ports collection, - do - - &prompt.root; cd /usr/ports -&prompt.root; make fetch - - For all the tarballs for a single ports directory, do - - &prompt.root; cd /usr/ports/directory -&prompt.root; make fetch - - and for just one port — well, I think you have guessed - already. - - - - 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? - - A. Yes. If you know, for example, ftp.FreeBSD.org is much closer than sites - listed in MASTER_SITES, do as following - example. - - &prompt.root; cd /usr/ports/directory -&prompt.root; make MASTER_SITE_OVERRIDE=ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch - - - - Q. I want to know what files make is going to need before it - tries to pull them down. - - A. make fetch-list will display a list of - the files needed for a port. - - - - 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. - - A. Doing make extract will stop it after it - has fetched and extracted the source code. - - - - 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 make - extract, but for patches? - - A. Yep, make patch is what you want. You - will probably find the PATCH_DEBUG option useful - as well. And by the way, thank you for your efforts! - - - - 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? - - A. Yes, with version 2.6.3 of gcc (the - version shipped with FreeBSD 2.1.0 and 2.1.5), the - option could result in buggy code unless you - used the option as well. - (Most of the ports do not use ). You - should be able to specify the compiler options - used by something like - - - &prompt.root; make CFLAGS='-O2 -fno-strength-reduce' install - - or by editing /etc/make.conf, but - unfortunately not all ports respect this. The surest way is to do - make configure, 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. - - - - 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? - - A. Look in the INDEX file in - /usr/ports. 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: - - &prompt.user; cd /usr/ports -&prompt.user; make search key=lisp - - - - Q. I went to install the foo port but the - system suddenly stopped compiling it and starting compiling the - bar port. What is going on? - - A. The foo port needs something that is - supplied with bar — for instance, if - foo uses graphics, bar might - have a library with useful graphics processing routines. Or - bar might be a tool that is needed to compile the - foo port. - - - - Q. I installed the - grizzle 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? - - A. No problem, just do - - &prompt.root; pkg_delete grizzle-6.5 - - Alternatively, you can do - - &prompt.root; cd /usr/ports/somewhere/grizzle -&prompt.root; make deinstall - - - - - 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?? - - A. Not at all, you can find it out by doing - - &prompt.root; pkg_info -a | grep grizzle -Information for grizzle-6.5: -grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arcade game. - - - - 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? - - 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 - - &prompt.root; cd /usr/ports -&prompt.root; make clean - - which will go through all the ports subdirectories and delete - everything except the skeletons for each port. - - - - Q. I tried that and it still left all those tarballs or - whatever you called them in the distfiles - directory. Can I delete those as well? - - A. Yes, if you are sure you have finished with them, those can - go as well. - - - - Q. I like having lots and lots of programs to play with. Is - there any way of installing all the ports in one go? - - A. Just do - - &prompt.root; cd /usr/ports -&prompt.root; make install - - - - 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? - - 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. - - - - Q. I really do not want to spend all day staring at the - monitor. Any better ideas? - - A. OK, do this before you go to bed/work/the local - park:- - - &prompt.root cd /usr/ports -&prompt.root; make -DBATCH install - - This will install every port that does not - require user input. Then, when you come back, do - - &prompt.root; cd /usr/ports -&prompt.root; make -DIS_INTERACTIVE install - - to finish the job. - - - - Q. At work, we are using frobble, 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? - - A. No problem, assuming you know how to make patches for your - changes:- - - &prompt.root; cd /usr/ports/somewhere/frobble -&prompt.root; make extract -&prompt.root; cd work/frobble-2.8 -[Apply your patches] -&prompt.root; cd ../.. -&prompt.root; make package - - - - Q. This ports stuff is really clever. I am desperate to find - out how you did it. What is the secret? - - A. Nothing secret about it at all, just look at the - bsd.ports.mk and - bsd.ports.subdir.mk files in your makefiles - directory. - - - Readers with an aversion to intricate shell-scripts are - advised not to follow this link...) - - - - - - - Making a port yourself - - Contributed by &a.jkh;, &a.gpalmer;, &a.asami;, &a.obrien;, - and &a.hoek;. 28 August 1996. - - So, now you are interested in making your own port or upgrading - an existing one? Great! - - 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 . - - When this document is not sufficiently detailed, you should refer to - /usr/ports/Mk/bsd.port.mk, 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;. - - - Only a fraction of the overridable variables - (VAR) are mentioned in - this document. Most (if not all) are documented at the start of - bsd.port.mk. This file users a non-standard tab - setting. Emacs and - Vim should recognise the setting on loading - the file. Both vi and ex can be - set to use the correct value by typing :set tabstop=4 - once the file has been loaded. - - - - Quick Porting - - This section tells you how to do a quick port. In many cases, it - is not enough, but we will see. - - First, get the original tarball and put it into - DISTDIR, which defaults to - /usr/ports/distfiles. - - - 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. - - - - Writing the <filename>Makefile</filename> - - The minimal Makefile would look something - like this: - - -# 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> - - See if you can figure it out. Do not worry about the contents - of the $Id$ 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 sample Makefile section. - - - - Writing the description files - - There are three description files that are required for any - port, whether they actually package or not. They are - COMMENT, DESCR, and - PLIST, and reside in the - pkg subdirectory. - - - <filename>COMMENT</filename> - - This is the one-line description of the port. - Please 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: - - -A cat chasing a mouse all over the screen - - - - <filename>DESCR</filename> - - This is a longer description of the port. One to a few - paragraphs concisely explaining what the port does is - sufficient. - - - This is not a manual or an in-depth - description on how to use or compile the port! Please - be careful if you are copying from the - README or manpage; 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 one of the websites with - WWW: so that automated tools will work - correctly. - - - It is recommended that you sign your name at the end of this - file, as in: - - -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 - - - - <filename>PLIST</filename> - - 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 - /usr/local or - /usr/X11R6). If you are using the - MANn variables (as - you should be), do not list any manpages here. - - Here is a small example: - - -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 - - Refer to the &man.pkg.create.1; man page for details on the - packing list. - - - 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 @dirrm - lines as necessary to remove them when the port is - deleted. - - 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. - - Creating a packing list manually can be a very tedious - task. If the port installs a large numbers of files, creating the packing list - automatically might save time. - - - - - - Creating the checksum file - - Just type make makesum. The ports make rules - will automatically generate the file - files/md5. - - - - Testing the port - - 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. - - - - PLIST does not contain anything not - installed by your port - - - - PLIST contains everything that is - installed by your port - - - - Your port can be installed multiple times using the - reinstall target - - - - Your port cleans up - after itself upon deinstall - - - - - Recommended test ordering - - - make install - - - - make package - - - - make deinstall - - - - pkg_add package-name - - - - - make deinstall - - - - make reinstall - - - - make package - - - - Make sure that there are not any warnings issued in any of the - package and - deinstall 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. - - - - Checking your port with <command>portlint</command> - - Please use portlint to see if your port - conforms to our guidelines. The portlint program - is part of the ports collection. In particular, your may want to - check if the Makefile is in - the right shape and the package is named - appropriately. - - - - Submitting the port - - First, make sure you have read the Do's and Dont's section. - - 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 work - directory or the pkgname.tgz package, so delete - them now. Next, simply include the output of shar `find - port_dir` in a bug report and send it with the - &man.send-pr.1; program (see Bug - Reports and General Commentary 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 - ports and class - change-request. (Do not mark the report - confidential!) - - One more time, do not include the original source - distfile, the work directory, or the package - you built with make package. - - - In the past, we asked you to upload new port submissions in - our ftp site (ftp.FreeBSD.org). This - is no longer recommended as read access is turned off on that - incoming/ directory of that site due to the - large amount of pirated software showing up there. - - - 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?!? :) - - - - - Slow Porting - - 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. - - - How things work - - First, this is the sequence of events which occurs when the user - first types make in your port's directory, and - you may find that having bsd.port.mk in another - window while you read this really helps to understand it. - - But do not worry if you do not really understand what - bsd.port.mk is doing, not many people do... - :> - - - - - The fetch target is run. The - fetch target is responsible for making - sure that the tarball exists locally in - DISTDIR. If fetch - cannot find the required files in DISTDIR it - will look up the URL MASTER_SITES, which is - set in the Makefile, as well as our main ftp site at ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/, - where we put sanctioned distfiles as backup. It will then - attempt to fetch the named distribution file with - FETCH, assuming that the requesting site has - direct access to the Internet. If that succeeds, it will save - the file in DISTDIR for future use and - proceed. - - - - The extract target is run. It - looks for your port's distribution file (typically a gzip'd - tarball) in DISTDIR and unpacks it into a - temporary subdirectory specified by WRKDIR - (defaults to work). - - - - The patch target is run. First, - any patches defined in PATCHFILES are - applied. Second, if any patches are found in - PATCHDIR (defaults to the - patches subdirectory), they are applied at - this time in alphabetical order. - - - - The configure target is run. This - can do any one of many different things. - - - - If it exists, scripts/configure is - run. - - - - If HAS_CONFIGURE or - GNU_CONFIGURE is set, - WRKSRC/configure is - run. - - - - If USE_IMAKE is set, - XMKMF (default: xmkmf - -a) is run. - - - - - - The build target is run. This is - responsible for descending into the port's private working - directory (WRKSRC) and building it. If - USE_GMAKE is set, GNU make - will be used, otherwise the system make will - be used. - - - - The above are the default actions. In addition, you can define - targets - pre-something or - post-something, - or put scripts with those names, in the scripts - subdirectory, and they will be run before or after the default - actions are done. - - For example, if you have a post-extract - target defined in your Makefile, and a file - pre-build in the scripts - subdirectory, the post-extract target will - be called after the regular extraction actions, and the - pre-build script will be executed before the - default build rules are done. It is recommended that you use - Makefile 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. - - The default actions are done by the - bsd.port.mk targets - do-something. - For example, the commands to extract a port are in the target - do-extract. If you are not happy with the - default target, you can fix it by redefining the - do-something - target in your Makefile. - - - The “main” targets (e.g., - extract, - configure, 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 - do-extract, but never ever touch - extract! - - - Now that you understand what goes on when the user types - make, let us go through the recommended steps to - create the perfect port. - - - - Getting the original sources - - Get the original sources (normally) as a compressed tarball - (foo.tar.gz or - foo.tar.Z) and copy - it into DISTDIR. Always use - mainstream sources when and where you - can. - - 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 - MASTER_SITES to reflect your choice. - - 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 public_html/ directory on - freefall), we can “house” it ourselves - by putting it on - ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/LOCAL_PORTS/ - as the last resort. Please refer to this location as - MASTER_SITE_LOCAL. Send mail to the &a.ports;if - you are not sure what to do. - - 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 MASTER_SITES. This will prevent users - from getting checksum mismatch 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 - MASTER_SITES. - - If your port requires some additional `patches' that are - available on the Internet, fetch them too and put them in - DISTDIR. 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 PATCHFILES below). - - - - Modifying the port - - 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 careful - track 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. - - If your port requires significant user interaction/customization - to compile or install, you should take a look at one of Larry Wall's - classic Configure 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. - - - 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. - - - - - Patching - - 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 - patch-xx where - xx denotes the sequence in which the - patches will be applied — these are done in - alphabetical order, thus aa - first, ab second and so on. These files should - be stored in PATCHDIR, from where they will be - automatically applied. All patches should be relative to - WRKSRC (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., patch-aa and - patch-ab both changing - WRKSRC/foobar.c). - - - - Configuring - - Include any additional customization commands to your - configure script and save it in the - scripts subdirectory. As mentioned above, you - can also do this as Makefile targets and/or - scripts with the name pre-configure or - post-configure. - - - - Handling user input - - If your port requires user input to build, configure or install, - then set IS_INTERACTIVE in your Makefile. This - will allow “overnight builds” to skip your port if the - user sets the variable BATCH in his environment (and - if the user sets the variable INTERACTIVE, then - only those ports requiring interaction are - built). - - It is also recommended that if there are reasonable default - answers to the questions, you check the - PACKAGE_BUILDING variable and turn off the - interactive script when it is set. This will allow us to build the - packages for CD-ROMs and ftp. - - - - - Configuring the Makefile - - Configuring the Makefile is pretty simple, and again we suggest - that you look at existing examples before starting. Also, there is a - sample Makefile 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. - - Now, consider the following problems in sequence as you design - your new Makefile: - - - The original source - - Does it live in DISTDIR 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 EXTRACT_CMD, - EXTRACT_BEFORE_ARGS, - EXTRACT_AFTER_ARGS, - EXTRACT_SUFX, or DISTFILES - variables, depending on how alien a format your port's distribution - file is. (The most common case is - EXTRACT_SUFX=.tar.Z, when the tarball is - condensed by regular compress, not gzip.) - - In the worst case, you can simply create your own - do-extract target to override the default, - though this should be rarely, if ever, necessary. - - - - <makevar>DISTNAME</makevar> - - You should set DISTNAME to be the base name - of your port. The default rules expect the distribution file list - (DISTFILES) to be named - DISTNAMEEXTRACT_SUFX which, if - it is a normal tarball, is going to be something like - foozolix-1.0.tar.gz for a setting of - DISTNAME=foozolix-1.0. - - The default rules also expect the tarball(s) to extract into a - subdirectory called - work/DISTNAME, e.g. - work/foozolix-1.0/. - - 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 - DISTFILES explicitly. If only a subset of - DISTFILES are actual extractable archives, then - set them up in EXTRACT_ONLY, which will override - the DISTFILES list when it comes to extraction, - and the rest will be just left in DISTDIR for - later use. - - - - <makevar>PKGNAME</makevar> - - If DISTNAME does not conform to our guidelines for a good package - name, you should set the PKGNAME - variable to something better. See the abovementioned guidelines for - more details. - - - - <makevar>CATEGORIES</makevar> - - When a package is created, it is put under - /usr/ports/packages/All and links are made from - one or more subdirectories of - /usr/ports/packages. The names of these - subdirectories are specified by the variable - CATEGORIES. 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 categories and pick the ones - that are suitable for your port. - - 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 categories section for more - discussion about how to pick the right categories. - - 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. - - - There is no error checking for category names. make - package will happily create a new directory if you - mistype the category name, so be careful! - - - - - <makevar>MASTER_SITES</makevar> - - Record the directory part of the ftp/http-URL pointing at the - original tarball in MASTER_SITES. Do not forget - the trailing slash (/)! - - The make macros will try to use this - specification for grabbing the distribution file with - FETCH if they cannot find it already on the - system. - - 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! - - 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 - MASTER_SITE_XCONTRIB, - MASTER_SITE_GNU, - MASTER_SITE_PERL_CPAN, - MASTER_SITE_TEX_CTAN, and - MASTER_SITE_SUNSITE. Simply set - MASTER_SITE_SUBDIR to the path with in the - archive. Here is an example: - - -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications - - The user can also set the MASTER_SITE_* - variables in /etc/make.conf to override our - choices, and use their favorite mirrors of these popular archives - instead. - - - - <makevar>PATCHFILES</makevar> - - If your port requires some additional patches that are available - by ftp or http, set PATCHFILES to the names of - the files and PATCH_SITES to the URL of the - directory that contains them (the format is the same as - MASTER_SITES). - - If the patch is not relative to the top of the source tree - (i.e., WKRSRC) because it contains some extra - pathnames, set PATCH_DIST_STRIP accordingly. For - instance, if all the pathnames in the patch have an extra - foozolix-1.0/ in front of the filenames, then set - PATCH_DIST_STRIP=-p1. - - Do not worry if the patches are compressed, they will be - decompressed automatically if the filenames end with - .gz or .Z. - - If the patch is distributed with some other files, such as - documentation, in a gzip'd tarball, you cannot just use - PATCHFILES. If that is the case, add the name - and the location of the patch tarball to - DISTFILES and MASTER_SITES. - Then, from the pre-patch target, apply the - patch either by running the patch command from there, or copying the - patch file into the PATCHDIR directory and - calling it - patch-xx. - - - 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 pre-clean - target. - - - - - <makevar>MAINTAINER</makevar> - - Set your mail-address here. Please. :) - - For detailed description of the responsibility of maintainers, - refer to MAINTAINER on - Makefiles section. - - - - Dependencies - - 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. - - - <makevar>LIB_DEPENDS</makevar> - - This variable specifies the shared libraries this port depends - on. It is a list of - lib:dir:target - tuples where lib is the name of the - shared library, and dir is the - directory in which to find it in case it is not available, and - target is the target to call in that - directory. For example, LIB_DEPENDS= - jpeg.9:${PORTSDIR}/graphics/jpeg:install - will check for a shared jpeg library with major version 9, and - descend into the graphics/jpeg subdirectory - of your ports tree to build and install it if it is not found. - The target part can be omitted if it is - equal to DEPENDS_TARGET (which defaults to - install). - - - The lib part is an argument given - to ldconfig -r | grep -wF. There shall be no - regular expressions in this variable. - - - The dependency is checked twice, once from within the - extract target and then from within the - install target. Also, the name of the - dependency is put in to the package so that - pkg_add will automatically install it if it is - not on the user's system. - - - - <makevar>RUN_DEPENDS</makevar> - - This variable specifies executables or files this port depends - on during run-time. It is a list of - path:dir:target - tuples where path is the name of the - executable or file, and dir is the - directory in which to find it in case it is not available, and - target is the target to call in that - directory. If path starts with a slash - (/), it is treated as a file and its existence - is tested with test -e; otherwise, it is - assumed to be an executable, and which -s is - used to determine if the program exists in the user's search - path. - - For example, - - -RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ - wish8.0:${PORTSDIR}/x11-toolkits/tk80 - - will check if the file or directory - /usr/local/etc/innd exists, and build and - install it from the news/inn subdirectory of - the ports tree if it is not found. It will also see if an - executable called wish8.0 is in your search - path, and descend into the x11-toolkits/tk80 - subdirectory of your ports tree to build and install it if it is - not found. - - - In this case, innd 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. - - - The dependency is checked from within the - install target. Also, the name of the - dependency is put in to the package so that - pkg_add will automatically install it if it is - not on the user's system. The target - part can be omitted if it is the same - DEPENDS_TARGET. - - - - <makevar>BUILD_DEPENDS</makevar> - - This variable specifies executables or files this port - requires to build. Like RUN_DEPENDS, it is a - list of - path:dir:target - tuples. For example, BUILD_DEPENDS= - unzip:${PORTSDIR}/archivers/unzip will check - for an executable called unzip, and descend - into the archivers/unzip subdirectory of your - ports tree to build and install it if it is not found. - - - “build” here means everything from extracting to - compilation. The dependency is checked from within the - extract target. The - target part can be omitted if it is - the same as DEPENDS_TARGET - - - - - <makevar>FETCH_DEPENDS</makevar> - - This variable specifies executables or files this port - requires to fetch. Like the previous two, it is a list of - path:dir:target - tuples. For example, FETCH_DEPENDS= - ncftp2:${PORTSDIR}/net/ncftp2 will check for an - executable called ncftp2, and descend into the - net/ncftp2 subdirectory of your ports tree to - build and install it if it is not found. - - The dependency is checked from within the - fetch target. The - target part can be omitted if it is the - same as DEPENDS_TARGET. - - - - <makevar>DEPENDS</makevar> - - 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 - dir:target, - as there is nothing to check, unlike the previous four. The - target part can be omitted if it is the - same as DEPENDS_TARGET. - - - - Common dependency variables - - Define USE_XLIB=yes if your port requires - the X Window System to be installed (it is implied by - USE_IMAKE). Define - USE_GMAKE=yes if your port requires GNU - make instead of BSD make. - Define USE_AUTOCONF=yes if your port requires - GNU autoconf to be run. Define USE_QT=yes if - your port uses the latest qt toolkit. Use - USE_PERL5=yes 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.) - - - - Notes on dependencies - - As mentioned above, the default target to call when a - dependency is required is DEPENDS_TARGET. - It defaults to install. This is a user - variable; is is never defined in a port's - Makefile. If your port needs a special way - to handle a dependency, use the :target part of - the *_DEPENDS variables instead of redefining - DEPENDS_TARGET. - - When you type make clean, its dependencies - are automatically cleaned too. If you do not wish this to happen, - define the variable NOCLEANDEPENDS in your - environment. - - To depend on another port unconditionally, it is customary to - use the string nonexistent as the first field - of BUILD_DEPENDS or - RUN_DEPENDS. 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 - - -BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract - - will always descend to the JPEG port and extract it. - - Do not use DEPENDS 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 - BUILD_DEPENDS and - RUN_DEPENDS instead—at least the - intention will be clear. - - - - - Building mechanisms - - If your package uses GNU make, set - USE_GMAKE=yes. If your package uses - configure, set - HAS_CONFIGURE=yes. If your package uses GNU - configure, set - GNU_CONFIGURE=yes (this implies - HAS_CONFIGURE). If you want to give some extra - arguments to configure (the default argument list - --prefix=${PREFIX} for GNU - configure and empty for non-GNU - configure), set those extra arguments in - CONFIGURE_ARGS. If your package uses GNU - autoconf, set - USE_AUTOCONF=yes. This implies - GNU_CONFIGURE, and will cause - autoconf to be run before - configure. - - If your package is an X application that creates - Makefiles from Imakefiles - using imake, then set - USE_IMAKE=yes. This will cause the configure - stage to automatically do an xmkmf -a. If the - flag is a problem for your port, set - XMKMF=xmkmf. If the port uses - imake but does not understand the - install.man target, - NO_INSTALL_MANPAGES=yes should be set. In - addition, the author of the original port should be shot. :> - - If your port's source Makefile has - something else than all as the main build - target, set ALL_TARGET accordingly. Same goes - for install and - INSTALL_TARGET. - - - - - Special considerations - - There are some more things you have to take into account when you - create a port. This section explains the most common of those. - - - <command>ldconfig</command> - - If your port installs a shared library, add a - post-install target to your - Makefile that runs ${LDCONFIG} - -m on the directory where the new library is installed - (usually PREFIX/lib) to - register it into the shared library cache. - - Also, add a matching @exec /sbin/ldconfig -m - and @unexec /sbin/ldconfig -R pair to your - pkg/PLIST 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: - - -lib/libtvl80.so.1 -@exec /sbin/ldconfig -m %D/lib -@unexec /sbin/ldconfig -R - - Never, ever, ever add a line that says - ldconfig without any arguments to your - Makefile or pkg/PLIST. - This will reset the shared library cache to the contents of - /usr/lib 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…) - - - - - ELF support - - 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. - - 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. - - - Moving a.out libraries out of the way - - A.out libraries should be moved out of - /usr/local/lib and similar to an - aout subdirectory. (If you do not move them out - of the way, ELF ports will happily overwrite a.out libraries.) The - move-aout-libs target in the 3.0-CURRENT - src/Makefile (called from - aout-to-elf) 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. - - - - Format - - 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 `objformat` 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.) - - - If a port only works for a.out, set - BROKEN_ELF to a string describing the reason - why. Such ports will be skipped during a build on an ELF - system. - - - - - <makevar>PORTOBJFORMAT</makevar> - - bsd.port.mk will set - PORTOBJFORMAT to aout or - elf and export it in the environments - CONFIGURE_ENV, SCRIPTS_ENV and - MAKE_ENV. (It's always going to be - aout in 2.2-STABLE). It is also passed to - PLIST_SUB as - PORTOBJFORMAT=${PORTOBJFORMAT}. (See comment on - ldconfig lines below.) - - The variable is set using this line in - bsd.port.mk: - - -PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout - - Ports' make processes should use this variable to decide what to - do. However, if the port's configure script - already automatically detects an ELF system, it is not necessary to - refer to PORTOBJFORMAT. - - - - Building shared libraries - - The following are differences in handling shared libraries for - a.out and ELF. - - - - Shared library versions - - An ELF shared library should be called - libfoo.so.M - where M is the single version number, - and an a.out library should be called - libfoo.so.M.N - where M is the major version and - N is the the minor version number. - Do not mix those; never install an ELF - shared library called - libfoo.so.N.M - or an a.out shared library (or symlink) called - libfoo.so.N. - - - - Linker command lines - - Assuming cc -shared is used rather than - ld directly, the only difference is that you - need to add - - on the command line for ELF. - - - - You need to install a symlink from - libfoo.so to - libfoo.so.N to make - ELF linkers happy. Since it should be listed in - PLIST 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 - PORTOBJFORMAT. - - - - <makevar>LIB_DEPENDS</makevar> - - All port Makefiles are edited to remove minor numbers from - LIB_DEPENDS, and also to have the regexp support - removed. (E.g., foo\\.1\\.\\(33|40\\) becomes - foo.2.) They will be matched using grep - -wF. - - - - <filename>PLIST</filename> - - PLIST should contain the short (ELF) shlib - names if the a.out minor number is zero, and the long (a.out) names - otherwise. bsd.port.mk will automatically add - .0 to the end of short shlib lines if - PORTOBJFORMAT equals aout, and - will delete the minor number from long shlib names if - PORTOBJFORMAT equals - elf. - - 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 - NO_FILTER_SHLIBS. This will turn off the editing - of PLIST mentioned in the previous - paragraph. - - - - <literal>ldconfig</literal> - - The ldconfig line in Makefiles should - read: - - -${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m .... - - In PLIST it should read; - - -@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ... -@unexec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -R - - This is to ensure that the correct ldconfig - will be called depending on the format of the package, not the - default format of the system. - - - - - <makevar>MASTERDIR</makevar> - - 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 - Makefile in all but one of the directories if you - use variables cleverly. In the sole Makefiles, - you can use MASTERDIR to specify the directory - where the rest of the files are. Also, use a variable as part of - PKGNAME so - the packages will have different names. - - This will be best demonstrated by an example. This is part of - japanese/xdvi300/Makefile; - - -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 - - japanese/xdvi300 also has all the regular - patches, package files, etc. If you type make - there, it will take the default value for the resolution (300) and - build the port normally. - - As for other resolutions, this is the entire - xdvi118/Makefile; - - -RESOLUTION= 118 -MASTERDIR= ${.CURDIR}/../xdvi300 - -.include ${MASTERDIR}/Makefile - - (xdvi240/Makefile and - xdvi400/Makefile are similar). The - MASTERDIR definition tells - bsd.port.mk that the regular set of - subdirectories like PATCHDIR and - PKGDIR are to be found under - xdvi300. The RESOLUTION=118 - line will override the RESOLUTION=300 line in - xdvi300/Makefile and the port will be built with - resolution set to 118. - - - - Shared library versions - - First, please read our policy on - shared library versioning 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 jpeg-6b 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. - - 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 libfoo.so.3.2 and - libfoo.so.4.0 in the system, there is no way to - tell the linker to link a particular application to - libfoo.so.3.2. It is essentially completely - overshadowed in terms of compilation-time linkage. In this case, the - only solution is to rename the base part of the - shared library. For instance, change - libfoo.so.4.0 to - libfoo4.so.1.0 so both version 3.2 and 4.0 can be - linked from other ports. - - - - Manpages - - The MAN[1-9LN] variables will automatically add - any manpages to pkg/PLIST (this means you must - not list manpages in the - PLIST—see generating PLIST for more). It also - makes the install stage automatically compress or uncompress manpages - depending on the setting of NOMANCOMPRESS in - /etc/make.conf. - - If your port tries to install multiple names for manpages using - symlinks or hardlinks, you must use the MLINKS - variable to identify these. The link installed by your port will - be destroyed and recreated by bsd.port.mk - to make sure it points to the correct file. Any manpages - listed in MLINKS must not be listed in the - PLIST. - - To specify whether the manpages are compressed upon installation, - use the MANCOMPRESSED variable. This variable can - take three values, yes, no and - maybe. yes means manpages are - already installed compressed, no means they are - not, and maybe means the software already respects - the value of NOMANCOMPRESS so - bsd.port.mk does not have to do anything - special. - - MANCOMPRESSED is automatically set to - yes if USE_IMAKE is set and - NO_INSTALL_MANPAGES is not set, and to - no otherwise. You do not have to explicitly define - it unless the default is not suitable for your port. - - If your port anchors its man tree somewhere other than - PREFIX, you can use the - MANPREFIX 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 - MANsectPREFIX (where - sect is one of 1-9, - L or N). - - If your manpages go to language-specific subdirectories, set the - name of the languages to MANLANG. The value of - this variable defaults to "" (i.e., English - only). - - Here is an example that puts it all together. - - -MAN1= foo.1 -MAN3= bar.3 -MAN4= baz.4 -MLINKS= foo.1 alt-name.8 -MANLANG= "" ja -MAN3PREFIX= ${PREFIX}/share/foobar -MANCOMPRESSED= yes - - This states that six files are installed by this port; - - -${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 - - Additionally ${PREFIX}/man/man8/alt-name.8.gz - 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. - - - - - Ports that require Motif - - 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 - x11-toolkits/lesstif) 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). - - - <makevar>REQUIRES_MOTIF</makevar> - - 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. - - - - <makevar>MOTIFLIB</makevar> - - This variable will be set by bsd.port.mk to - be the appropriate reference to the Motif library. Please patch the - source to use this wherever the Motif library is referenced in the - Makefile or - Imakefile. - - There are two common cases: - - - - If the port refers to the Motif library as - -lXm in its Makefile or - Imakefile, simply substitute - ${MOTIFLIB} for it. - - - - If the port uses XmClientLibs in its - Imakefile, change it to - ${MOTIFLIB} ${XTOOLLIB} - ${XLIB}. - - - - Note that MOTIFLIB (usually) expands to - -L/usr/X11R6/lib -lXm or - /usr/X11R6/lib/libXm.a, so there is no need to - add -L or -l in front. - - - - - X11 fonts - - If your port installs fonts for the X Window system, put them in - X11BASE/lib/X11/fonts/local. - 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 /etc/XF86Config. - - - - Info files - - The new version of texinfo (included in 2.2.2-RELEASE and onwards) - contains a utility called install-info to add and - delete entries to the dir file. If your port - installs any info documents, please follow this instructions so your - port/package will correctly update the user's - PREFIX/info/dir 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 - beautiful listing, so please bear with me! - - First, this is what you (as a porter) need to know - - &prompt.user; install-info --help -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. : - - - This program will not actually install info - files; it merely inserts or deletes entries in the - dir file. - - - Here's a seven-step procedure to convert ports to use - install-info. I will use - editors/emacs as an example. - - - - Look at the texinfo sources and make a patch to insert - @dircategory and @direntry - statements to files that do not have them. This is part of my - patch: - - ---- ./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 - : - - The format should be self-explanatory. Many authors leave a - dir 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). - - - Note that you can put only one info entry per file because - of a bug in install-info --delete that - deletes only the first entry if you specify multiple entries in - the @direntry section. - - - You can give the dir entries to - install-info as arguments - ( and ) 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 three places - (Makefile and - @exec/@unexec of - PLIST; see below). However, if you have a - Japanese (or other multibyte encoding) info files, you will have - to use the extra arguments to install-info - because makeinfo cannot handle those texinfo - sources. (See Makefile and - PLIST of japanese/skk - for examples on how to do this). - - - - Go back to the port directory and do a make clean; - make 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 - make; but many Makefiles - do not include correct dependencies for info files. In - emacs' case, I had to patch the main - Makefile.in so it will descend into the - man subdirectory to rebuild the info - pages. - - ---- ./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) - - The second hunk was necessary because the default target in - the man subdir is called - info, while the main - Makefile wants to call - all. I also deleted the installation of - the info info file because we already have - one with the same name in /usr/share/info - (that patch is not shown here). - - - - If there is a place in the Makefile that - is installing the dir file, delete it. Your - port may not be doing it. Also, remove any commands that are - otherwise mucking around with the dir - file. - - ---- ./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); \ - - - - (This step is only necessary if you are modifying an existing - port.) Take a look at pkg/PLIST and delete - anything that is trying to patch up info/dir. - They may be in pkg/INSTALL or some other - file, so search extensively. - - -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 - - - - Add a post-install target to the - Makefile to create a dir - file if it is not there. Also, call - install-info with the installed info - files. - - -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> - - Do not use anything other than - /usr/share/info/dir and the above command to - create a new info file. In fact, I would add the first three lines - of the above patch to bsd.port.mk if you (the - porter) would not have to do it in PLIST by - yourself anyway. - - - - Edit PLIST and add equivalent - @exec statements and also - @unexec for pkg_delete. You - do not need to delete info/dir with - @unexec. - - -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 - - - The @unexec install-info --delete - commands have to be listed before the info files themselves so - they can read the files. Also, the @exec - install-info commands have to be after the info - files and the @exec command that creates the - the dir file. - - - - - Test and admire your - work. :). Check the - dir file before and after each step. - - - - - - The <filename>pkg/</filename> subdirectory - - There are some tricks we have not mentioned yet about the - pkg/ subdirectory that come in handy - sometimes. - - - <filename>MESSAGE</filename> - - If you need to display a message to the installer, you may place - the message in pkg/MESSAGE. This capability is - often useful to display additional installation steps to be taken - after a pkg_add or to display licensing - information. - - - The pkg/MESSAGE file does not need to be - added to pkg/PLIST. 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 - post-install target yourself. - - - - - <filename>INSTALL</filename> - - If your port needs to execute commands when the binary package - is installed with pkg_add you can do this via the - pkg/INSTALL script. This script will - automatically be added to the package, and will be run twice by - pkg_add. The first time will as INSTALL - ${PKGNAME} PRE-INSTALL and the second time as - INSTALL ${PKGNAME} POST-INSTALL. - $2 can be tested to determine which mode - the script is being run in. The PKG_PREFIX - environmental variable will be set to the package installation - directory. See &man.pkg.add.1; for - additional information. - - - This script is not run automatically if you install the port - with make install. If you are depending on it - being run, you will have to explicitly call it from your port's - Makefile. - - - - - <filename>REQ</filename> - - If your port needs to determine if it should install or not, you - can create a pkg/REQ “requirements” - script. It will be invoked automatically at - installation/deinstallation time to determine whether or not - installation/deinstallation should proceed. - - - - Changing <filename>PLIST</filename> based on make - variables - - Some ports, particularly the p5- ports, need to change their - PLIST 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 PLIST of - %%OSREL%%, %%PERL_VER%%, and - %%PERL_VERSION%% will be substituted for - appropriately. The value of %%OSREL%% is the - numeric revision of the operating system (e.g., - 2.2.7). %%PERL_VERSION%% is - the full version number of perl (e.g., 5.00502) - and %%PERL_VER%% is the perl version number minus - the patchlevel (e.g., 5.005). - - If you need to make other substitutions, you can set the - PLIST_SUB variable with a list of - VAR=VALUE - pairs and instances of - %%VAR%%' will be - substituted with VALUE in the - PLIST. - - For instance, if you have a port that installs many files in a - version-specific subdirectory, you can put something like - - -OCTAVE_VERSION= 2.0.13 -PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} - - in the Makefile and use - %%OCTAVE_VERSION%% wherever the version shows up - in PLIST. That way, when you upgrade the port, - you will not have to change dozens (or in some cases, hundreds) of - lines in the PLIST. - - This substitution (as well as addition of any man pages) will be done between - the do-install and - post-install targets, by reading from - PLIST and writing to TMPPLIST - (default: - WRKDIR/.PLIST.mktmp). So if - your port builds PLIST on the fly, do so in or - before do-install. Also, if your port - needs to edit the resulting file, do so in - post-install to a file named - TMPPLIST. - - - - Changing the names of files in the - <filename>pkg</filename> subdirectory - - All the filenames in the pkg subdirectory - are defined using variables so you can change them in your - Makefile if need be. This is especially useful - when you are sharing the same pkg subdirectory - among several ports or have to write to one of the above files (see - writing to places other than - WRKDIR for why it is a bad idea to write - directly in to the pkg subdirectory. - - Here is a list of variable names and their default - values. - - - - - - Variable - Default value - - - - - - COMMENT - ${PKGDIR}/DESCR - - - - DESCR - ${PKGDIR}/DESCR - - - - PLIST - ${PKGDIR}/PLIST - - - - PKGINSTALL - ${PKGDIR}/PKGINSTALL - - - - PKGDEINSTALL - ${PKGDIR}/PKGDEINSTALL - - - - PKGREQ - ${PKGDIR}/REQ - - - - PKGMESSAGE - ${PKGDIR}/MESSAGE - - - - - - Please change these variables rather than overriding - PKG_ARGS. If you change - PKG_ARGS, those files will not correctly be - installed in /var/db/pkg upon install from a - port. - - - - - Licensing Problems - - 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. - - - 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;. - - - There are two variables you can set in the Makefile to handle the - situations that arise frequently: - - - - If the port has a “do not sell for profit” type of - license, set the variable NO_CDROM 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. - - - - 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 NO_PACKAGE 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. - - - - 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 RESTRICTED to be the string - describing the reason why. For such ports, the distfiles/packages - will not be available even from our ftp sites. - - - - - The GNU General Public License (GPL), both version 1 and 2, - should not be a problem for ports. - - - - If you are a committer, make sure you update the - ports/LEGAL file too. - - - - - Upgrading - - 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 - ports/ports-current directory of the ftp mirror - sites. You may also use CVSup to keep your whole ports collection - up-to-date, as described in . - - The next step is to send a mail to the maintainer, if one is - listed in the port's Makefile. 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). - - 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 superedit and the original as in our tree - is superedit.bak, then send us the result of - diff -ruN superedit.bak superedit). 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 - ports). 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. - - - Once again, please use &man.diff.1; and not &man.shar.1; to send - updates to existing ports! - - - - - <anchor id="porting-dads">Do's and Dont's - - 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 - Bug Reports and General - Commentary. 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. - - - Strip Binaries - - Do strip binaries. If the original source already strips the - binaries, fine; otherwise you should add a - post-install rule to to it yourself. Here is an - example; - - -post-install: - strip ${PREFIX}/bin/xdl - - Use the &man.file.1; command on the installed executable to - check whether the binary is stripped or not. If it does not say - not stripped, it is stripped. - - - - INSTALL_* macros - - Do use the macros provided in bsd.port.mk - to ensure correct modes and ownership of files in your own - *-install targets. They are: - - - - INSTALL_PROGRAM is a command to install - binary executables. - - - - INSTALL_SCRIPT is a command to install - executable scripts. - - - - INSTALL_DATA is a command to install - sharable data. - - - - INSTALL_MAN is a command to install - manpages and other documentation (it does not compress - anything). - - - - These are basically the install command with - all the appropriate flags. See below for an example on how to use - them. - - - - <makevar>WRKDIR</makevar> - - Do not write anything to files outside - WRKDIR. WRKDIR is the only - place that is guaranteed to be writable during the port build (see - compiling ports from CDROM for an - example of building ports from a read-only tree). If you need to - modify some file in PKGDIR, do so by redefining a variable, not by - writing over it. - - - - <makevar>WRKDIRPREFIX</makevar> - - Make sure your port honors WRKDIRPREFIX. - Most ports do not have to worry about this. In particular, if you - are referring to a WRKDIR of another port, note - that the correct location is - WRKDIRPREFIXPORTSDIR/subdir/name/work not PORTSDIR/subdir/name/work or .CURDIR/../../subdir/name/work or some such. - - Also, if you are defining WRKDIR yourself, - make sure you prepend - ${WKRDIRPREFIX}${.CURDIR} in the - front. - - - - Differentiating operating systems and OS versions - - 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. - - The preferred way to tell 4.3BSD/Reno (1990) and newer versions - of the BSD code apart is by using the BSD macro - defined in <sys/param.h>. Hopefully that - file is already included; if not, add the code: - - -#if (defined(__unix__) || defined(unix)) && !defined(USG) -#include <sys/param.h> -#endif - - to the proper place in the .c file. We - believe that every system that defines these two symbols has - sys/param.h. If you find a system that - does not, we would like to know. Please send mail to the - &a.ports;. - - Another way is to use the GNU Autoconf style of doing - this: - - -#ifdef HAVE_SYS_PARAM_H -#include <sys/param.h> -#endif - - Do not forget to add -DHAVE_SYS_PARAM_H to the - CFLAGS in the Makefile for - this method. - - Once you have sys/param.h included, you may - use: - - -#if (defined(BSD) && (BSD >= 199103)) - - 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). - - Use: - - -#if (defined(BSD) && (BSD >= 199306)) - - 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). - - The value of the BSD macro is - 199506 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 - __FreeBSD__ macro should be used instead. - - Use sparingly: - - - - __FreeBSD__ is defined in all versions of - FreeBSD. Use it if the change you are making - only affects FreeBSD. Porting gotchas like - the use of sys_errlist[] vs - strerror() are Berkeleyisms, not FreeBSD - changes. - - - - In FreeBSD 2.x, __FreeBSD__ is defined to - be 2. In earlier versions, it is - 1. Later versions will bump it to match - their major version number. - - - - 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 BSD macros described above. If - there actually is a FreeBSD specific change (such as special - shared library options when using ld) then it - is OK to use __FreeBSD__ and #if - __FreeBSD__ > 1 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: - - -#if __FreeBSD__ >= 2 -#include <osreldate.h> -# if __FreeBSD_version >= 199504 - /* 2.0.5+ release specific code here */ -# endif -#endif - - - - - - Release - __FreeBSD_version - - - - - - 2.0-RELEASE - 119411 - - - - 2.1-CURRENTs - 199501, 199503 - - - - 2.0.5-RELEASE - 199504 - - - - 2.2-CURRENT before 2.1 - 199508 - - - - 2.1.0-RELEASE - 199511 - - - - 2.2-CURRENT before 2.1.5 - 199512 - - - - 2.1.5-RELEASE - 199607 - - - - 2.2-CURRENT before 2.1.6 - 199608 - - - - 2.1.6-RELEASE - 199612 - - - - 2.1.7-RELEASE - 199612 - - - - 2.2-RELEASE - 220000 - - - - 2.2.1-RELEASE - 220000 (no change) - - - - 2.2-STABLE after 2.2.1-RELEASE - 220000 (no change) - - - - 2.2-STABLE after texinfo-3.9 - 221001 - - - - 2.2-STABLE after top - 221002 - - - - 2.2.2-RELEASE - 222000 - - - - 2.2-STABLE after 2.2.2-RELEASE - 222001 - - - - 2.2.5-RELEASE - 225000 - - - - 2.2-STABLE after 2.2.5-RELEASE - 225001 - - - - 2.2-STABLE after ldconfig -R merge - 225002 - - - - 2.2.6-RELEASE - 226000 - - - - 2.2.7-RELEASE - 227000 - - - - 2.2-STABLE after 2.2.7-RELEASE - 227001 - - - - 2.2-STABLE after semctl(2) change - 227002 - - - - 2.2.8-RELEASE - 228000 - - - - 2.2-STABLE after 2.2.8-RELEASE - 228001 - - - - 3.0-CURRENT before mount(2) change - 300000 - - - - 3.0-CURRENT after mount(2) change - 300001 - - - - 3.0-CURRENT after semctl(2) change - 300002 - - - - 3.0-CURRENT after ioctl arg changes - 300003 - - - - 3.0-CURRENT after ELF conversion - 300004 - - - - 3.0-RELEASE - 300005 - - - - 3.0-CURRENT after 3.0-RELEASE - 300006 - - - - 3.0-STABLE after 3/4 branch - 300007 - - - - 3.1-RELEASE - 310000 - - - - 3.1-STABLE after 3.1-RELEASE - 310001 - - - - 3.1-STABLE after C++ constructor/destructor order - change - 310002 - - - - 3.2-STABLE - 320001 - - - - 4.0-CURRENT after 3/4 branch - 400000 - - - - 4.0-CURRENT after change in dynamic linker - handling - 400001 - - - - 4.0-CURRENT after C++ constructor/destructor - order change - 400002 - - - - 4.0-CURRENT after functioning dladdr(3) - 400003 - - - - 4.0-CURRENT after newbus - 400004 - - - - 4.0-CURRENT after suser(9) API change - 400005 - - - - 4.0-CURRENT after cdevsw registration change - 400006 - - - - 4.0-CURRENT after the addition of so_cred for - socket level credentials - 400007 - - - - 4.0-CURRENT after the addition of a poll syscall - wrapper to libc_r - 400008 - - - - 4.0-CURRENT after the change of the kernel's - dev_t type to struct - spacinfo pointer - 400009 - - - - - - - - - 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. - - - In the hundreds of ports that have been done, there have only - been one or two cases where __FreeBSD__ 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. - - - - Writing something after - <filename>bsd.port.mk</filename> - - Do not write anything after the .include - <bsd.port.mk> line. it usually can be avoided by - including bsd.port.pre.mk somewhere in the - middle of your Makefile and - bsd.port.post.mk at the end. - - - You need to include either the - pre.mk/post.mk pair or - bsd.port.mk only; do not mix these two. - - - bsd.port.pre.mk only defines a few - variables, which can be used in tests in the - Makefile, bsd.port.post.mk - defines the rest. - - Here are some important variables defined in - bsd.port.pre.mk (this is not the complete list, - please read bsd.port.mk for the complete - list). - - - - - - Variable - Description - - - - - - ARCH - The architecture as returned by uname - -m (e.g., i386) - - - - OPSYS - The operating system type, as returned by - uname -s (e.g., - FreeBSD) - - - - OSREL - The release version of the operating system (e.g., - 2.1.5 or - 2.2.7) - - - - OSVERSION - The numeric version of the operating system, same as - __FreeBSD_version. - - - - PORTOBJFORMAT - The object format of the system - (aout or elf - - - - LOCALBASE - The base of the “local” tree (e.g., - /usr/local/) - - - - X11BASE - The base of the “X11” tree (e.g., - /usr/X11R6) - - - - PREFIX - Where the port installs itself (see more on - PREFIX). - - - - - - - If you have to define the variables - USE_IMAKE, USE_X_PREFIX, or - MASTERDIR, do so before including - bsd.port.pre.mk. - - - Here are some examples of things you can write after - bsd.port.pre.mk; - - -# 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 - - - - Install additional documentation - - 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 PREFIX/share/doc. - This can be done, like the previous item, in the - post-install target. - - Create a new directory for your port. The directory name should - reflect what the port is. This usually means - PKGNAME 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 - PKGNAME. - - Make the installation dependent to the variable - NOPORTDOCS so that users can disable it in - /etc/make.conf, like this: - - -post-install: -.if !defined(NOPORTDOCS) - ${MKDIR}${PREFIX}/share/doc/xv - ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv -.endif - - Do not forget to add them to pkg/PLIST too! - (Do not worry about NOPORTDOCS here; there is - currently no way for the packages to read variables from - /etc/make.conf.) - - Also you can use the pkg/MESSAGE file to - display messages upon installation. See the using - pkg/MESSAGE section for - details. - - - MESSAGE does not need to be added to - pkg/PLIST). - - - - - <makevar>DIST_SUBDIR</makevar> - - Do not let your port clutter - /usr/ports/distfiles. 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., - Makefile), set DIST_SUBDIR - to the name of the port (PKGNAME without the - version part should work fine). This will change - DISTDIR from the default - /usr/ports/distfiles to - /usr/ports/distfiles/DIST_SUBDIR, - and in effect puts everything that is required for your port into - that subdirectory. - - It will also look at the subdirectory with the same name on the - backup master site at ftp.FreeBSD.org. - (Setting DISTDIR explicitly in your - Makefile will not accomplish this, so please use - DIST_SUBDIR.) - - - This does not affect the MASTER_SITES you - define in your Makefile. - - - - - Package information - - Do include package information, i.e. - COMMENT, DESCR, and - PLIST, in pkg. - - - Note that these files are not used only for packaging anymore, - and are mandatory now, even if - NO_PACKAGE is set. - - - - - RCS strings - - 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 ($) signs, and - typically start with $Id or - $RCS. - - - - Recursive diff - - Using the recurse () option to - diff 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, Makefiles when the port uses - Imake or GNU configure, etc., - are unnecessary and should be deleted. If you had to edit - configure.in and run - autoconf to regenerate - configure, do not take the diffs of - configure (it often grows to a few thousand - lines!); define USE_AUTOCONF=yes and take the - diffs of configure.in. - - Also, if you had to delete a file, then you can do it in the - post-extract 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. - - - - <makevar>PREFIX</makevar> - - Do try to make your port install relative to - PREFIX. (The value of this variable will be set - to LOCALBASE (default - /usr/local), unless - USE_X_PREFIX or USE_IMAKE is - set, in which case it will be X11BASE (default - /usr/X11R6).) - - Not hard-coding /usr/local or - /usr/X11R6 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 imake, this is - automatic; otherwise, this can often be done by simply replacing the - occurrences of /usr/local (or - /usr/X11R6 for X ports that do not use imake) - in the various scripts/Makefiles in the port to read - PREFIX, as this variable is automatically passed - down to every stage of the build and install processes. - - Do not set USE_X_PREFIX unless your port - truly require it (i.e., it links against X libs or it needs to - reference files in X11BASE). - - The variable PREFIX can be reassigned in your - Makefile or in the user's environment. - However, it is strongly discouraged for individual ports to set this - variable explicitly in the Makefiles. - - Also, refer to programs/files from other ports with the - variables mentioned above, not explicit pathnames. For instance, if - your port requires a macro PAGER to be the full - pathname of less, use the compiler flag: - - --DPAGER=\"${PREFIX}/bin/less\" - - or - - --DPAGER=\"${LOCALBASE}/bin/less\" - - if this is an X port, instead of - -DPAGER=\"/usr/local/bin/less\". This way it will - have a better chance of working if the system administrator has - moved the whole `/usr/local' tree somewhere else. - - - - Subdirectories - - Try to let the port put things in the right subdirectories of - PREFIX. 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 lib, which does - not bode well with the BSD paradigm. Many of the files should be - moved to one of the following: etc - (setup/configuration files), libexec - (executables started internally), sbin - (executables for superusers/managers), info - (documentation for info browser) or share - (architecture independent files). See man &man.hier.7; for details, - the rules governing - /usr pretty much apply to - /usr/local too. The exception are ports - dealing with USENET “news”. They may use - PREFIX/news as a destination - for their files. - - - - Cleaning up empty directories - - Do make your ports clean up after themselves when they are - deinstalled. This is usually accomplished by adding - @dirrm lines for all directories that are - specifically created by the port. You need to delete subdirectories - before you can delete parent directories. - - - : -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 - - However, sometimes @dirrm will give you - errors because other ports also share the same subdirectory. You - can call rmdir from @unexec to - remove only empty directories without warning. - - -@unexec rmdir %D/share/doc/gimp 2>/dev/null || true - - This will neither print any error messages nor cause - pkg_delete to exit abnormally even if - PREFIX/share/doc/gimp is not - empty due to other ports installing some files in there. - - - - UIDs - - If your port requires a certain user to be on the installed - system, let the pkg/INSTALL script call - pw to create it automatically. Look at - net/cvsup-mirror for an example. - - 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 - japanese/Wnn for an example. - - 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. - - -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 - - 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. - - - - Do things rationally - - The Makefile 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 - .if construct instead of a shell - if construct, not redefining - do-extract if you can redefine - EXTRACT* instead, and using - GNU_CONFIGURE instead of CONFIGURE_ARGS - += --prefix=${PREFIX}. - - - - Respect <makevar>CFLAGS</makevar> - - The port should respect the CFLAGS variable. - If it does not, please add NO_PACKAGE=ignores - cflags to the Makefile. - - - - Configuration files - - If your port requires some configuration files in - PREFIX/etc, do - not just install them and list them in - pkg/PLIST. That will cause - pkg_delete to delete files carefully edited by - the user and a new installation to wipe them out. - - Instead, install sample files with a suffix - (filename.sample - will work well) and print out a message pointing out that the - user has to copy and edit the file before the software can be made - to work. - - - - Portlint - - Do check your work with portlint - before you submit or commit it. - - - - Feedback - - 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. - - - - Miscellanea - - The files pkg/DESCR, - pkg/COMMENT, and pkg/PLIST - should each be double-checked. If you are reviewing a port and feel - they can be worded better, do so. - - Do not copy more copies of the GNU General Public License into - our system, please. - - Please be careful to note any legal issues! Do not let us - illegally distribute software! - - - - If you are stuck… - - Do look at existing examples and the - bsd.port.mk file before asking us questions! - ;) - - Do ask us questions if you have any trouble! Do not just beat - your head against a wall! :) - - - - - A Sample <filename>Makefile</filename> - - Here is a sample Makefile that you can use to - create a new port. Make sure you remove all the extra comments (ones - between brackets)! - - 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 portlint to check the - Makefile. - - -[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> - - - - Automated package list creation - - First, make sure your port is almost complete, with only - PLIST missing. Create an empty - PLIST. - - &prompt.root; touch PLIST - - Next, create a new set of directories which your port can be - installed, and install any dependencies. - - &prompt.root; mtree -U -f /etc/mtree/BSD.local.dist -d -e -p /var/tmp/port-name -&prompt.root; make depends PREFIX=/var/tmp/port-name - - Store the directory structure in a new file. - - &prompt.root; (cd /var/tmp/port-name && find * \! -type d) > OLD-DIRS - - If your port honours PREFIX (which it should) - you can then install the port and create the package list. - - &prompt.root; make install PREFIX=/var/tmp -&prompt.root; (cd /var/tmp/port-name && find * \! -type d) > pkg/PLIST - - You must also add any newly created directories to the packing - list. - - &prompt.root; (cd /var/tmp/port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm#' >> pkg/PLIST - - 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 Makefile under - MANn, and not in the - package list. User configuration files should be removed, or - installed as - filename.sample. Any - libraries installed by the port should be listed as specified in the - ldconfig section. - - - - Package Names - - 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! - - The package name should look like - language-name-compiled.specifics-version.numbers. - - If your DISTNAME does not look like that, set - PKGNAME to something in that format. - - - - FreeBSD strives to support the native language of its users. - The language- 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 - ja for Japanese, ru for - Russian, vi for Vietnamese, - zh for Chinese, ko for - Korean and de for German. - - - - The name 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 R or - V) you may use capital letters at your - discretion. There is a tradition of naming Perl 5 modules by - prepending p5- and converting the double-colon - separator to a hyphen; for example, the - Data::Dumper module becomes - p5-Data-Dumper. If the software in question - has numbers, hyphens, or underscores in its name, you may include - them as well (like kinput2). - - - - If the port can be built with different hardcoded defaults (usually - part of the directory name in a family of ports), the - -compiled.specifics part should state - the compiled-in defaults (the hyphen is optional). Examples are - papersize and font units. - - - - The version string should be a period-separated list of - integers and single lowercase alphabetics. The only exception is - the string pl (meaning `patchlevel'), which can - be used only when there are no major and - minor version numbers in the software. - - - - Here are some (real) examples on how to convert a - DISTNAME into a suitable - PKGNAME: - - - - - - Distribution Name - Package Name - Reason - - - - - - mule-2.2.2. - mule-2.2.2 - No changes required - - - - XFree86-3.1.2 - XFree86-3.1.2 - No changes required - - - - EmiClock-1.0.2 - emiclock-1.0.2 - No uppercase names for single programs - - - - gmod1.4 - gmod-1.4 - Need a hyphen before version numbers - - - - xmris.4.0.2 - xmris-4.0.2 - Need a hyphen before version numbers - - - - rdist-1.3alpha - rdist-1.3a - No strings like alpha - allowed - - - - es-0.9-beta1 - es-0.9b1 - No strings like beta - allowed - - - - v3.3beta021.src - tiff-3.3 - What the heck was that anyway? - - - - tvtwm - tvtwm-pl11 - Version string always required - - - - piewm - piewm-1.0 - Version string always required - - - - xvgr-2.10pl1 - xvgr-2.10.1 - pl allowed only when no - major/minor version numbers - - - - gawk-2.15.6 - ja-gawk-2.15.6 - Japanese language version - - - - psutils-1.13 - psutils-letter-1.13 - Papersize hardcoded at package build time - - - - pkfonts - pkfonts300-1.0 - Package for 300dpi fonts - - - - - - 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 - 1.0 (like the piewm example above). Otherwise, ask - the original author or use the date string - (yy.mm.dd) as the version. - - - - Categories - - 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. - - - Current list of categories - - First, this is the current list of port categories. Those - marked with an asterisk (*) are - virtual categories—those that do not have - a corresponding subdirectory in the ports tree. - - - For non-virtual categories, you will find a one-line - description in the pkg/COMMENT file in that - subdirectory (e.g., - archivers/pkg/COMMENT). - - - - - - - Category - Description - - - - - - afterstep* - Ports to support AfterStep window manager - - - - archivers - Archiving tools. - - - - astro - Astronomical ports. - - - - audio - Sound support. - - - - benchmarks - Benchmarking utilities. - - - - biology - Biology-related software. - - - - cad - Computer aided design tools. - - - - chinese - Chinese language support. - - - - comms - Communication software. Mostly software to talk to - your serial port. - - - - converters - Character code converters. - - - - databases - Databases. - - - - deskutils - Things that used to be on the desktop before - computers were invented. - - - - devel - 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. - - - - editors - General editors. Specialized editors go in the section - for those tools (e.g., a mathematical-formula editor will go - in math). - - - - elisp - Emacs-lisp ports. - - - - emulators - Emulators for other operating systems. Terminal - emulators do not belong - here—X-based ones should go to - x11 and text-based ones to either - comms or misc, - depending on the exact functionality. - - - - ftp - FTP client and server utilities. If your - port speaks both FTP and HTTP, put it in - ftp with a secondary - category of www. - - - - games - Games. - - - - german - German language support. - - - - graphics - Graphics utilities. - - - - irc - Internet Chat Relay utilities. - - - - japanese - Japanese language support. - - - - java - Java language support. - - - - kde* - Ports that form the K Desktop Environment - (kde). - - - - korean - Korean language support. - - - - lang - Programming languages. - - - - mail - Mail software. - - - - math - Numerical computation software and other utilities - for mathematics. - - - - mbone - MBone applications. - - - - misc - 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 misc with something else in - your CATEGORIES line, that means you can - safely delete misc and just put the port - in that other subdirectory! - - - - net - Miscellaneous networking software. - - - - news - USENET news software. - - - - offix* - Ports from the OffiX suite. - - - - palm - Software support for the 3Com Palm(tm) series. - - - - perl5* - Ports that require perl version 5 to run. - - - - plan9* - Various programs from Plan9. - - - - print - Printing software. Desktop publishing tools - (previewers, etc.) belong here too. - - - - python* - Software written in python. - - - - russian - Russian language support. - - - - security - Security utilities. - - - - shells - Command line shells. - - - - sysutils - System utilities. - - - - tcl75* - Ports that use tcl version 7.5 to run. - - - - tcl76* - Ports that use tcl version 7.6 to run. - - - - tcl80* - Ports that use tcl version 8.0 to run. - - - - tcl81* - Ports that use tcl version 8.1 to run. - - - - textproc - Text processing utilities. It does not include - desktop publishing tools, which go to print/. - - - - tk41* - Ports that use tk version 4.1 to run. - - - - tk42* - Ports that use tk version 4.2 to run. - - - - tk80* - Ports that use tk version 8.0 to run. - - - - tk81* - Ports that use tk version 8.1 to run. - - - - vietnamese - Vietnamese language support. - - - - windowmaker* - Ports to support the WindowMaker window - manager - - - - www - Software related to the World Wide Web. HTML language - support belong here too. - - - - x11 - 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 USE_XLIB (implied by - USE_IMAKE) and put it in appropriate - categories. Also, many of them go into other - x11-* categories (see below). - - - - x11-clocks - X11 clocks. - - - - x11-fm - X11 file managers. - - - - x11-fonts - X11 fonts and font utilities. - - - - x11-servers - X11 servers. - - - - x11-toolkits - X11 toolkits. - - - - x11-wm - X11 window managers. - - - - - - - - Choosing the right category - - 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. - - - - Language specific categories always come first. For - example, if your port installs Japanese X11 fonts, then your - CATEGORIES line would read japanese - x11-fonts. - - - - Specific categories win over less-specific ones. For - instance, an HTML editor should be listed as www - editors, not the other way around. Also, you do not - need to list net when the port belongs to - either of irc, mail, - mbone, news, - security, or www. - - - - x11 is used as a secondary category only - when the primary category is a natural language. In particular, - you should not put x11 in the category line - for X applications. - - - - If your port truly does not belong anywhere else, put it in - misc. - - - - If you are not sure about the category, please put a comment to - that effect in your send-pr 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.) - - - - - Changes to this document and the ports system - - 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 the - bsd.port.mk CVS log. - - - - That is It, Folks! - - Boy, this sure was a long tutorial, wasn't it? Thanks for - following us to here, really. - - 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! :) - - - - - 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 @@ - - - - PPP and SLIP - - 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: user (sometimes - referred to as iijppp) and - kernel. The procedures for configuring both types of - PPP, and for setting up SLIP are described in this chapter. - - - Setting up User PPP - - 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: - -
- This is a user process PPP software package. Normally, PPP is - implemented as a part of the kernel (e.g. as managed by - pppd) 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 - (tun). -
- - 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. - - 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 pppd. Unless - otherwise stated, all commands in this section should be executed as - root. - - 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 show version 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 www.Awfulhak.org. - - - Before you start - - This document assumes you are in roughly this position: - - 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. - - You are going to need the following information to hand: - - - - Your ISPs phone number(s). - - - - 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. - - - - The IP addresses of one or more nameservers. Normally, you - will be given two IP numbers. You must have - this information for PPP version 1.x - unless you run your own nameserver. From version 2 onwards, - PPP supports nameserver address - negotiation. If your ISP supports this, then using the command - enable dns in your config file will tell - PPP to set the nameservers for - you. - - - - The following information may have been supplied by your ISP, but - is not strictly necessary: - - - - 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 - default route. 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. - - This IP number is referred to as HISADDR - by ppp. - - - - Your ISP's netmask. If your ISP hasn't given you this - information, you can safely use a netmask of 255.255.255.0. - - 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. - - - - If you do not have any of the required information, contact your - ISP and make sure they provide it to you. - - - - Building a ppp ready kernel - - As the description states, ppp uses the kernel - tun device. It is necessary to make sure - that your kernel has support for this device compiled in. - - To check this, go to your kernel compile directory - (/sys/i386/conf or - /sys/pc98/conf) and examine your kernel - configuration file. It needs to have the line - - -pseudo-device tun 1 - - in it somewhere. The stock GENERIC kernel has - this as standard, so if you have not installed a custom kernel or you - do not have a /sys directory, you do not have to - change anything. - - If your kernel configuration file does not have this line in it, - or you need to configure more than one tun 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 16 instead - of 1), then you should add the line, re-compile, - re-install and boot the new kernel. Please refer to the Configuring the FreeBSD Kernel section - for more information on kernel configuration. - - You can check how many tunnel devices your current kernel has by - typing the following: - - &prompt.root; ifconfig -a -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 - - - This case shows four tunnel devices, two of which are currently - configured and being used. It should be noted that the - RUNNING 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 RUNNING. - - If you have a kernel without the tun 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. - - You may also wish to take this opportunity to configure a - firewall. Details can be found in the Firewalls section. - - - - Check the tun device - - Most users will only require one tun - device (/dev/tun0). If you have used more (i.e., - a number other than 1 in the - pseudo-device line in the kernel configuration - file) then alter all references to tun0 below - to reflect whichever device number you are using. - - The easiest way to make sure that the - tun0 device is configured correctly is to - re-make it. To do this, execute the following commands: - - &prompt.root; cd /dev -&prompt.root; ./MAKEDEV tun0 - - If you require 16 tunnel devices in your kernel, you will need to - create more than just tun0: - - &prompt.root; cd /dev -&prompt.root; ./MAKEDEV tun15 - - Also, to confirm that the kernel is configured correctly, the - following command should give the indicated output: - - &prompt.root; ifconfig tun0 -tun0: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 1500 - - The RUNNING flag may not yet be set, in which - case you will see: - - &prompt.root; ifconfig tun0 -tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 - - - - Name Resolution Configuration - - 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 /etc/hosts (man 5 - hosts). The second is the Internet Domain Name Service - (DNS), a distributed data base, the discussion of which is beyond the - scope of this document. - - This section describes briefly how to configure your - resolver. - - 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 /etc/host.conf. - Do not call this file - /etc/hosts.conf (note the extra - s) as the results can be confusing. - - - Edit the <filename>/etc/host.conf</filename> file - - This file should contain the following two lines (in this - order): - - -hosts -bind - - These instructs the resolver to first look in the file - /etc/hosts, and then to consult the DNS if the - name was not found. - - - - Edit the <filename>/etc/hosts</filename>(5) file - - 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 foo.bar.com with the IP - address 10.0.0.1, - /etc/hosts should contain: - - -127.0.0.1 localhost -10.0.0.1 foo.bar.com foo - - The first line defines the alias localhost as a - synonym for the current machine. Regardless of your own IP address, - the IP address for this line should always be 127.0.0.1. The second line maps the name - foo.bar.com (and the shorthand - foo) to the IP address 10.0.0.1. - - If your provider allocates you a static IP address and name, - then use these in place of the 10.0.0.1 entry. - - - - Edit the <filename>/etc/resolv.conf</filename> file - - /etc/resolv.conf 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): - - -nameserver x.x.x.x -nameserver y.y.y.y -domain bar.com - - The x.x.x.x and - y.y.y.y - addresses are those given to you by your ISP. Add as many - nameserver lines as your ISP provides. The - domain line defaults to your hostname's domain, - and is probably unnecessary. Refer to the - resolv.conf manual page for details of other - possible entries in this file. - - If you are running PPP version 2 or greater, the enable - dns 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 - /etc/resolv.conf), PPP will rewrite the file - with the ISP-supplied values. - - - - - <command>ppp</command> Configuration - - Both user ppp and pppd (the kernel level - implementation of PPP) use configuration files located in the - /etc/ppp directory. The sample configuration - files provided are a good reference for user ppp, so don't delete - them. - - Configuring ppp 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). - - - PPP and Static IP addresses - - You will need to create a configuration file called - /etc/ppp/ppp.conf. It should look similar to - the example below. - - - Lines that end in a : start in the first - column, all other lines should be indented as shown using spaces - or tabs. - - - -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 x.x.x.x y.y.y.y 255.255.255.0 0.0.0.0 -10 add default HISADDR -11 enable dns - - Do not include the line numbers, they are just for reference in - this discussion. - - - - Line 1: - - - Identifies the default entry. Commands in this entry are - executed automatically when ppp is run. - - - - - Line 2: - - - Identifies the device to which the modem is connected. - COM1: is - /dev/cuaa0 and - COM2: is - /dev/cuaa1. - - - - - Line 3: - - - Sets the speed you want to connect at. If 115200 doesn't - work (it should with any reasonably new modem), try 38400 - instead. - - - - - Line 4: - - - 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. - - - - - Line 5: - - - Identifies an entry for a provider called - “provider”. - - - - - Line 6: - - - Sets the phone number for this provider. Multiple phone - numbers may be specified using the : or - | 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 :. 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 |. Always - quote the entire set of phone numbers as shown. - - - - - Line 7: - - - 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: - - J. Random Provider -login: foo -password: bar -protocol: ppp - - 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. - - If you're using PAP or CHAP, there will be no login at - this point, so your login string can be left blank. See PAP and CHAP - authentication for further details. - - - - - Line 8: - - - 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. - - - - - Line 9: - - - Sets the interface addresses. The string - x.x.x.x should be replaced by the - IP address that your provider has allocated to you. The - string y.y.y.y 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 10.0.0.2/0. If you need to use a - “guessed” address, make sure that you create an - entry in /etc/ppp/ppp.linkup as per the - instructions for PPP and - Dynamic IP addresses. If this line is omitted, - ppp cannot run in or - mode. - - - - - Line 10: - - - Adds a default route to your ISPs gateway. The special - word HISADDR is replaced with the gateway - address specified on line 9. It is important that this line - appears after line 9, otherwise HISADDR - will not yet be initialized. - - - - - Line 11: - - - 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 - /etc/resolv.conf with the correct - nameserver entries. - - - - - It is not necessary to add an entry to - ppp.linkup 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. - - Example configuration files can be found in the - /etc/ppp directory. - - - - PPP and Dynamic IP addresses - - If your service provider does not assign static IP numbers, - ppp can be configured to negotiate the local and - remote addresses. This is done by “guessing” an IP - number and allowing ppp to set it up correctly - using the IP Configuration Protocol (IPCP) after connecting. The - ppp.conf configuration is the same as PPP and Static IP addresses, - with the following change: - - -9 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 - - Again, do not include the line numbers, they are just for - reference in this discussion. Indentation of at least one space is - required. - - - - Line 9: - - - The number after the / 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. - - The last argument (0.0.0.0) tells PPP - to negotiate using address 0.0.0.0 rather than 10.0.0.1. Do not use - 0.0.0.0 as the first argument to - set ifaddr as it prevents PPP from setting - up an initial route in mode. - - - - - If you are running version 1.x of PPP, you will also need to - create an entry in /etc/ppp/ppp.linkup. - ppp.linkup is used after a connection has been - established. At this point, ppp will know what - IP addresses should really be used. The - following entry will delete the existing bogus routes, and create - correct ones: - - -1 provider: -2 delete ALL -3 add 0 0 HISADDR - - - - Line 1: - - - On establishing a connection, ppp will - look for an entry in ppp.linkup according - to the following rules: First, try to match the same label as - we used in ppp.conf. 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 MYADDR entry. - - - - - Line 2: - - - This line tells ppp to delete all - existing routes for the acquired tun interface (except the - direct route entry). - - - - - Line 3: - - - This line tells ppp to add a default - route that points to HISADDR. - HISADDR will be replaced with the IP number - of the gateway as negotiated in the IPCP. - - - - - See the pmdemand entry in the files - /etc/ppp/ppp.conf.sample and - /etc/ppp/ppp.linkup.sample for a detailed - example. - - Version 2 of PPP introduces “sticky routes”. Any - add or delete lines that - contain MYADDR or HISADDR will - be remembered, and any time the actual values of - MYADDR or HISADDR change, the - routes will be re-applied. This removes the necessity of repeating - these lines in ppp.linkup. - - - - Receiving incoming calls with <command>ppp</command> - - This section describes setting up ppp in a - server role. - - When you configure ppp 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 - - -enable proxy - - in your ppp.conf file. You should also confirm - that the /etc/rc.conf file (this file used to - be called /etc/sysconfig) contains the - following: - - -gateway=YES - - - Which getty? - - Configuring FreeBSD for Dialup - Services provides a good description on enabling dialup - services using getty. - - An alternative to getty is mgetty, - a smarter version of getty designed with dialup - lines in mind. - - The advantages of using mgetty is that it - actively talks to modems, meaning if port is - turned off in /etc/ttys then your modem won't - answer the phone. - - Later versions of mgetty (from 0.99beta - onwards) also support the automatic detection of PPP streams, - allowing your clients script-less access to your server. - - Refer to Mgetty and - AutoPPP for more information on - mgetty. - - - - PPP permissions - - ppp must normally be run as user id 0. If - however you wish to allow ppp to run in server - mode as a normal user by executing ppp as - described below, that user must be given permission to run - ppp by adding them to the - network group in - /etc/group. - - You will also need to give them access to one or more sections - of the configuration file using the allow - command: - - -allow users fred mary - - If this command is used in the default - section, it gives the specified users access to everything. - - - - Setting up a PPP shell for dynamic-IP users - - Create a file called /etc/ppp/ppp-shell - containing the following: - - -#!/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 - - This script should be executable. Now make a symbolic link - called ppp-dialup to this script using the - following commands: - - &prompt.root; ln -s ppp-shell /etc/ppp/ppp-dialup - - You should use this script as the shell - for all your dialup ppp users. This is an example from - /etc/password for a dialup PPP user with - username pchilds. (remember don't directly - edit the password file, use vipw) - - -pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup - - Create a /home/ppp directory that is - world readable containing the following 0 byte files - - -r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin --r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts - - which prevents /etc/motd from being - displayed. - - - - Setting up a PPP shell for static-IP users - - Create the ppp-shell file as above and - for each account with statically assigned IPs create a symbolic - link to ppp-shell. - - For example, if you have three dialup customers - fred, sam, and - mary, that you route class C networks for, - you would type the following: - - &prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred -&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam -&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary - - Each of these users dialup accounts should have their shell - set to the symbolic link created above. (ie. - mary's shell should be - /etc/ppp/ppp-mary). - - - - Setting up ppp.conf for dynamic-IP users - - The /etc/ppp/ppp.conf file should contain - something along the lines of - - -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 - - - The indenting is important. - - - The default: section is loaded for each - session. For each dialup line enabled in - /etc/ttys create an entry similar to the one - for ttyd0: above. Each line should get a - unique IP address from your pool of IP addresses for dynamic - users. - - - - Setting up <filename>ppp.conf</filename> for static-IP - users - - Along with the contents of the sample - /etc/ppp/ppp.conf above you should add a - section for each of the statically assigned dialup users. We will - continue with our fred, - sam, and mary - example. - - -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 - - The file /etc/ppp/ppp.linkup should also - contain routing information for each static IP user if required. - The line below would add a route for the 203.14.101.0 class C via the client's - ppp link. - - -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 - - - - More on <command>mgetty</command>, AutoPPP, and MS - extensions - - - <command>mgetty</command> and AutoPPP - - Configuring and compiling mgetty with the - AUTO_PPP option enabled allows - mgetty 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. - - This section assumes the user has successfully configured, - compiled, and installed a version of mgetty - with the AUTO_PPP option (v0.99beta or - later) - - Make sure your - /usr/local/etc/mgetty+sendfax/login.config - file has the following in it: - - -/AutoPPP/ - - /etc/ppp/ppp-pap-dialup - - This will tell mgetty to run the - ppp-pap-dialup script for detected PPP - connections. - - Create a file called - /etc/ppp/ppp-pap-dialup containing the - following (the file should be executable): - - -#!/bin/sh -exec /usr/sbin/ppp -direct pap$IDENT - - For each dialup line enabled in - /etc/ttys create a corresponding entry in - /etc/ppp/ppp.conf. This will happily - co-exist with the definitions we created above. - - -pap: - enable pap - set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40 - enable proxy - - Each user logging in with this method will need to have a - username/password in /etc/ppp/ppp.secret - file, or alternatively add the - - -enable passwdauth - - option to authenticate users via pap from the - /etc/password file. - - If you wish to assign some users a static IP number, you can - specify the number as the third argument in - /etc/ppp/ppp.secret. See - /etc/ppp/ppp.secret.sample for - examples. - - - - MS extensions - - It is possible to configure PPP to supply DNS and NetBIOS - nameserver addresses on demand. - - To enable these extensions with PPP version 1.x, the - following lines might be added to the relevant section of - /etc/ppp/ppp.conf. - - -enable msext -set ns 203.14.100.1 203.14.100.2 -set nbns 203.14.100.5 - - And for PPP version 2 and above: - - -accept dns -set dns 203.14.100.1 203.14.100.2 -set nbns 203.14.100.5 - - This will tell the clients the primary and secondary name - server addresses, and a netbios nameserver host. - - In version 2 and above, if the set dns - line is omitted, PPP will use the values found in - /etc/resolv.conf. - - - - - - PAP and CHAP authentication - - 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 login: prompt when you connect, but will - start talking PPP immediately. - - 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”. - - Referring back to the PPP and - Static IP addresses or PPP and Dynamic IP addresses - sections, the following alterations must be made: - - -7 set login -… -12 set authname MyUserName -13 set authkey MyPassword - - As always, do not include the line numbers, they are just for - reference in this discussion. Indentation of at least one space is - required. - - - - Line 7: - - - 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. - - - - - Line 12: - - - This line specifies your PAP/CHAP user name. You will - need to insert the correct value for - MyUserName. - - - - - Line 13: - - - This line specifies your PAP/CHAP password. You will need - to insert the correct value for - MyPassword. You may want to add an - additional line - - -15 accept PAP - - or - - -15 accept CHAP - - to make it obvious that this is the intention, but PAP and - CHAP are both accepted by default. - - - - - - - Changing your <command>ppp</command> configuration on the - fly - - It is possible to talk to the ppp 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: - - -set server /var/run/ppp-tun%d DiagnosticPassword 0177 - - This will tell PPP to listen to the specified unix-domain - socket, asking clients for the specified password before allowing - access. The %d in the name is replaced with the - tun device number that is in use. - - Once a socket has been set up, the - &man.pppctl.8; program may be used in scripts that wish to - manipulate the running program. - - - - - Final system configuration - - You now have ppp configured, but there are a - few more things to do before it is ready to work. They all involve - editing the /etc/rc.conf file (was - /etc/sysconfig). - - Working from the top down in this file, make sure the - hostname= line is set, e.g.: - - -hostname=foo.bar.com - - 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. - - Look for the network_interfaces variable. If - you want to configure your system to dial your ISP on demand, make - sure the tun0 device is added to the list, - otherwise remove it. - - -network_interfaces="lo0 tun0" ifconfig_tun0= - - - The ifconfig_tun0 variable should be empty, - and a file called /etc/start_if.tun0 should be - created. This file should contain the line - - -ppp -auto mysystem - - 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 - switch. Refer to the manual page for - further details. - - - Set the router program to NO with the - line - - -router_enable=NO (/etc/rc.conf) -router=NO (/etc/sysconfig) - - It is important that the routed daemon is not - started (it's started by default) as routed tends - to delete the default routing table entries created by - ppp. - - It is probably worth your while ensuring that the - sendmail_flags line does not include the - option, otherwise sendmail will - attempt to do a network lookup every now and then, possibly causing - your machine to dial out. You may try: - - -sendmail_flags="-bd" - - The upshot of this is that you must force - sendmail to re-examine the mail queue whenever the - ppp link is up by typing: - - &prompt.root; /usr/sbin/sendmail -q - - You may wish to use the !bg command in - ppp.linkup to do this automatically: - - -1 provider: -2 delete ALL -3 add 0 0 HISADDR -4 !bg sendmail -bd -q30m - - 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. - - All that is left is to reboot the machine. - - After rebooting, you can now either type - - &prompt.root; ppp - - and then dial provider to start the PPP - session, or, if you want ppp to establish sessions - automatically when there is outbound traffic (and you haven't created - the start_if.tun0 script), type - - &prompt.root; ppp -auto provider - - - - Summary - - To recap, the following steps are necessary when setting up ppp - for the first time: - - Client side: - - - - Ensure that the tun device is built - into your kernel. - - - - Ensure that the - tunX device file - is available in the /dev directory. - - - - Create an entry in /etc/ppp/ppp.conf. - The pmdemand example should suffice for most - ISPs. - - - - If you have a dynamic IP address, create an entry in - /etc/ppp/ppp.linkup. - - - - Update your /etc/rc.conf (or - sysconfig) file. - - - - Create a start_if.tun0 script if you - require demand dialing. - - - - Server side: - - - - Ensure that the tun device is built - into your kernel. - - - - Ensure that the - tunX device file - is available in the /dev directory. - - - - Create an entry in /etc/passwd (using the - &man.vipw.8; program). - - - - Create a profile in this users home directory that runs - ppp -direct direct-server or similar. - - - - Create an entry in /etc/ppp/ppp.conf. - The direct-server example should - suffice. - - - - Create an entry in - /etc/ppp/ppp.linkup. - - - - Update your /etc/rc.conf (or - sysconfig) file. - - - - - - Acknowledgments - - This section of the handbook was last updated on Monday Aug 10, - 1998 by &a.brian; - - Thanks to the following for their input, comments & - suggestions: - - &a.nik; - - &a.dirkvangulik; - - &a.pjc; - - - - - Setting up Kernel PPP - - Contributed by &a.gena;. - - Before you start setting up PPP on your machine make sure that - pppd is located in /usr/sbin and - directory /etc/ppp exists. - - pppd can work in two modes: - - - - as a “client”, i.e. you want to connect your machine - to outside world via PPP serial connection or modem line. - - - - as a “server”, i.e. your machine is located on the - network and used to connect other computers using PPP. - - - - In both cases you will need to set up an options file - (/etc/ppp/options or ~/.ppprc - if you have more then one user on your machine that uses PPP). - - You also will need some modem/serial software (preferably kermit) so - you can dial and establish connection with remote host. - - - Working as a PPP client - - I used the following /etc/ppp/options to - connect to CISCO terminal server PPP line. - - -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 - - To connect: - - - - 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) - - - - Exit kermit (without hanging up the line). - - - - enter: - - &prompt.root; /usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200 - - Use the appropriate speed and device name. - - - - Now your computer is connected with PPP. If the connection fails - for some reasons you can add the option to the - /etc/ppp/options file and check messages on the - console to track the problem - - Following /etc/ppp/pppup script will make all - 3 stages automatically: - - -#!/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 - - /etc/ppp/kermit.dial 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) - - Use the following /etc/ppp/pppdown script to - disconnect the PPP line: - - -#!/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 - - Check if PPP is still running - (/usr/etc/ppp/ppptest): - - -#!/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 - - Hangs up modem line - (/etc/ppp/kermit.hup): - - -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 - - Here is an alternate method using chat instead - of kermit. - - Contributed by &a.rhuff;. - - The following two files are sufficient to accomplish a pppd - connection. - - /etc/ppp/options: - - -/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 - - /etc/ppp/login.chat.script: - - (This should actually go into a single line.) - - -ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number> - CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id> - TIMEOUT 5 sword: <password> - - Once these are installed and modified correctly, all you need to - do is - - &prompt.root; pppd - - This sample based primarily on information provided by: Trev - Roydhouse <Trev.Roydhouse@f401.n711.z3.fidonet.org> and used by - permission. - - - - Working as a PPP server - - /etc/ppp/options: - - -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 - - Following /etc/ppp/pppserv script will enable - ppp server on your machine: - - -#!/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 - - Use this /etc/ppp/pppservdown script to stop - ppp server: - - -#!/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 - - Following kermit script will enable/disable autoanswer mode on - your modem (/etc/ppp/kermit.ans): - - -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 - - This /etc/ppp/kermit.dial 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. - - -; -; 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: - - - - - Setting up a SLIP Client - - Contributed by &a.asami; 8 Aug 1995. - - 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. - - First, determine which serial port your modem is connected to. I - have a symbolic link to /dev/modem from - /dev/cuaa1, 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 /etc and - .kermrc's all over the system! - - - /dev/cuaa0 is COM1, - cuaa1 is COM2, - etc. - - - Make sure you have - - -pseudo-device sl 1 - - in your kernel's config file. It is included in the - GENERIC kernel, so this will not be a problem - unless you deleted it. - - - Things you have to do only once - - - - Add your home machine, the gateway and nameservers to your - /etc/hosts file. Mine looks like - this: - - -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 - - 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.). - - - - Make sure you have before - in your /etc/host.conf. - Otherwise, funny things may happen. - - - - Edit the file /etc/rc.conf. Note that - you should edit the file /etc/sysconfig - instead if you are running FreeBSD previous to version - 2.2.2. - - - - Set your hostname by editing the line that says: - - -hostname=myname.my.domain - - You should give it your full Internet hostname. - - - - Add sl0 to the list of network interfaces by changing the - line that says: - - -network_interfaces="lo0" - - to: - - -network_interfaces="lo0 sl0" - - - - Set the startup flags of sl0 by adding a line: - - -ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up" - - - - Designate the default router by changing the line: - - -defaultrouter=NO - - to: - - -defaultrouter=slip-gateway - - - - - - Make a file /etc/resolv.conf which - contains: - - -domain HIP.Berkeley.EDU -nameserver 128.32.136.9 -nameserver 128.32.136.12 - - As you can see, these set up the nameserver hosts. Of course, - the actual domain names and addresses depend on your - environment. - - - - Set the password for root and toor (and any other accounts - that does not have a password). Use passwd, do not edit the - /etc/passwd or - /etc/master.passwd files! - - - - Reboot your machine and make sure it comes up with the correct - hostname. - - - - - - Making a SLIP connection - - - - Dial up, type slip 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: - - -# 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 - - (of course, you have to change the hostname and password to - fit yours). Then you can just type slip from - the kermit prompt to get connected. - - - 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. - - - - - Leave the kermit there (you can suspend it by - z) and as root, type: - - &prompt.root; slattach -h -c -s 115200 /dev/modem - - If you are able to ping hosts on the other - side of the router, you are connected! If it does not work, you - might want to try instead of - as an argument to slattach. - - - - - - How to shutdown the connection - - Type - - &prompt.root; kill -INT `cat /var/run/slattach.modem.pid` - - (as root) to kill slattach. Then go back to kermit - (fg if you suspended it) and exit from it - (q). - - The slattach man page says you have to use ifconfig sl0 - down to mark the interface down, but this does not seem to - make any difference for me. (ifconfig sl0 reports - the same thing.) - - 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. - - - - Troubleshooting - - If it does not work, feel free to ask me. The things that people - tripped over so far: - - - - Not using or in - slattach (I have no idea why this can be fatal, but adding this - flag solved the problem for at least one person) - - - - Using instead of - (might be hard to see the difference on some fonts). - - - - Try ifconfig sl0 to see your interface - status. I get: - - &prompt.root; ifconfig sl0 -sl0: flags=10<POINTOPOINT> - inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00 - - - - Also, netstat -r will give the routing - table, in case you get the "no route to host" messages from ping. - Mine looks like: - - &prompt.root; netstat -r -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) - - (this is after transferring a bunch of files, your numbers - should be smaller). - - - - - - - Setting up a SLIP Server - - Contributed by &a.ghelmer;. v1.0, 15 May - 1995. - - 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. - - 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. - - - Prerequisites - - 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 TCP/IP Network - Administration published by O'Reilly & Associates, - Inc. (ISBN Number 0-937175-82-X), or Douglas Comer's books on the - TCP/IP protocol. - - 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 - http://www.FreeBSD.org/; - otherwise, check the place where you found this document for a - document named dialup.txt 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 clocal for - directly-connected serial interfaces). - - - - Quick Overview - - 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 - /usr/sbin/sliplogin as the special user's shell. - The sliplogin program browses the file - /etc/sliphome/slip.hosts 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 - /etc/sliphome/slip.login to configure the SLIP - interface. - - - An Example of a SLIP Server Login - - For example, if a SLIP user ID were - Shelmerg, Shelmerg's entry - in /etc/master.passwd would look something like - this (except it would be all on one line): - - -Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin - - When Shelmerg logs in, - sliplogin will search - /etc/sliphome/slip.hosts for a line that had a - matching user ID; for example, there may be a line in - /etc/sliphome/slip.hosts that reads: - - -Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp - - sliplogin will find that matching line, hook - the serial line into the next available SLIP interface, and then - execute /etc/sliphome/slip.login like - this: - - -/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp - - If all goes well, /etc/sliphome/slip.login - will issue an ifconfig for the SLIP interface to - which sliplogin attached itself (slip interface - 0, in the above example, which was the first parameter in the list - given to slip.login) to set the local IP - address (dc-slip), remote IP address - (sl-helmer), network mask for the SLIP interface - (0xfffffc00), and any additional - flags (autocomp). If something goes wrong, - sliplogin usually logs good informational - messages via the daemon syslog facility, which - usually goes into /var/log/messages (see the - manual pages for &man.syslogd.8; and - &man.syslog.conf.5, and perhaps check - /etc/syslog.conf to see to which files - syslogd is logging). - - OK, enough of the examples — let us dive into setting up - the system. - - - - - Kernel Configuration - - FreeBSD's default kernels usually come with two SLIP interfaces - defined (sl0 and - sl1); you can use netstat - -i to see whether these interfaces are defined in your - kernel. - - Sample output from netstat -i: - - 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 - - The sl0 and sl1 - interfaces shown in netstat -i's output indicate - that there are two SLIP interfaces built into the kernel. (The - asterisks after the sl0 and sl1 - indicate that the interfaces are “down”.) - - 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 - /etc/rc.conf file (called - /etc/sysconfig in FreeBSD releases prior to - 2.2.2) and change the setting of the gateway - variable to . If you have an older system which - predates even the /etc/sysconfig file, then add - the following command: - - -sysctl -w net.inet.ip.forwarding = 1 - - to your /etc/rc.local file. - - You will then need to reboot for the new settings to take - effect. - - You will notice that near the end of the default kernel - configuration file (/sys/i386/conf/GENERIC) is a - line that reads: - - -pseudo-device sl 2 - - 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. - - Please refer to Configuring the - FreeBSD Kernel for help in reconfiguring your kernel. - - - - Sliplogin Configuration - - As mentioned earlier, there are three files in the - /etc/sliphome directory that are part of the - configuration for /usr/sbin/sliplogin (see - &man.sliplogin.8; for the actual manual page for - sliplogin): slip.hosts, which - defines the SLIP users & their associated IP addresses; - slip.login, which usually just configures the - SLIP interface; and (optionally) slip.logout, - which undoes slip.login's effects when the serial - connection is terminated. - - - <filename>slip.hosts</filename> Configuration - - /etc/sliphome/slip.hosts contains lines - which have at least four items, separated by whitespace: - - - - SLIP user's login ID - - - - Local address (local to the SLIP server) of the SLIP - link - - - - Remote address of the SLIP link - - - - Network mask - - - - The local and remote addresses may be host names (resolved to IP - addresses by /etc/hosts or by the domain name - service, depending on your specifications in - /etc/host.conf), and I believe the network mask - may be a name that can be resolved by a lookup into - /etc/networks. On a sample system, - /etc/sliphome/slip.hosts looks like - this: - - -# -# login local-addr remote-addr mask opt1 opt2 -# (normal,compress,noicmp) -# -Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp - - At the end of the line is one or more of the options. - - - - — no header compression - - - - — compress headers - - - - — compress headers if the - remote end allows it - - - - — disable ICMP packets (so any - “ping” packets will be dropped instead of using up - your bandwidth) - - - - Note that sliplogin under early releases of - FreeBSD 2 ignored the options that FreeBSD 1.x recognized, so the - options , , - , and had no effect - until support was added in FreeBSD 2.2 (unless your - slip.login script included code to make use of - the flags). - - 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 slips-prereqs section and/or - consult your IP network manager. - - 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 gated 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. - - 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 - /etc/sliphome/slip.login and - /etc/sliphome/slip.logout scripts to use - &man.arp.8; to manage the proxy-ARP entries in the SLIP server's - ARP table. - - - - <filename>slip.login</filename> Configuration - - The typical /etc/sliphome/slip.login file - looks like this: - - -#!/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 - - This slip.login file merely - ifconfig's the appropriate SLIP interface with - the local and remote addresses and network mask of the SLIP - interface. - - If you have decided to use the “proxy ARP” method - (instead of using a separate subnet for your SLIP clients), your - /etc/sliphome/slip.login file will need to look - something like this: - - -#!/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 - - The additional line in this slip.login, - arp -s $5 00:11:22:33:44:55 pub, 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. - - When using the example above, be sure to replace the Ethernet - MAC address (00:11:22:33:44:55) 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 - netstat -i; the second line of the output should - look something like: - - ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116 - - This indicates that this particular system's Ethernet MAC - address is 00:02:c1:28:5f:4a — the - periods in the Ethernet MAC address given by netstat - -i 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. - - - When you create /etc/sliphome/slip.login - and /etc/sliphome/slip.logout, the - “execute” bit (ie, chmod 755 - /etc/sliphome/slip.login /etc/sliphome/slip.logout) - must be set, or sliplogin will be unable to - execute it. - - - - - <filename>slip.logout</filename> Configuration - - /etc/sliphome/slip.logout is not strictly - needed (unless you are implementing “proxy ARP”), but if - you decide to create it, this is an example of a basic - slip.logout script: - - -#!/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 - - If you are using “proxy ARP”, you will want to have - /etc/sliphome/slip.logout remove the ARP entry - for the SLIP client: - - -#!/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 - - The arp -d $5 removes the ARP entry that - the “proxy ARP” slip.login added - when the SLIP client logged in. - - It bears repeating: make sure - /etc/sliphome/slip.logout has the execute - bit set for after you create it (ie, chmod - 755 /etc/sliphome/slip.logout). - - - - - Routing Considerations - - 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 gated on your FreeBSD SLIP - server so that it will tell your routers via appropriate routing - protocols about your SLIP subnet. - - - Static Routes - - 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. - - - - Running <command>gated</command> - - An alternative to the headaches of static routes is to install - gated 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 - gated from the ports - collection or retrieve and build it yourself from the - GateD anonymous ftp site; I believe the current version as - of this writing is gated-R3_5Alpha_8.tar.Z, - which includes support for FreeBSD “out-of-the-box”. - Complete information and documentation on gated - is available on the Web starting at the Merit GateD - Consortium. Compile and install it, and then write a - /etc/gated.conf file to configure your gated; - here is a sample, similar to what the author used on a FreeBSD SLIP - server: - - -# -# 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 { - xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections - } ; -} ; - -# -# Accept routes from RIP via ed Ethernet interfaces - -import proto rip interface ed { - all ; -} ; - - The above sample gated.conf file broadcasts - routing information regarding the SLIP subnet - xxx.xxx.yy via RIP onto the Ethernet; if - you are using a different Ethernet driver than the - ed driver, you will need to change the - references to the ed interface - appropriately. This sample file also sets up tracing to - /var/tmp/gated.output for debugging - gated's activity; you can certainly turn off the - tracing options if gated works OK for you. You - will need to change the xxx.xxx.yy's into - the network address of your own SLIP subnet (be sure to change the - net mask in the proto direct clause as - well). - - When you get gated built and installed and - create a configuration file for it, you will need to run - gated in place of routed on - your FreeBSD system; change the routed/gated - startup parameters in /etc/netstart as - appropriate for your system. Please see the manual page for - gated for information on - gated's command-line parameters. - - - - - Acknowledgments - - Thanks to these people for comments and advice regarding this - tutorial: - - - - &a.wilko; - - - - - - - - Piero Serini - - - Piero@Strider.Inet.IT - - - - - - - - - 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 @@ - - - - Printing - - Contributed by &a.kelly; 30 September - 1995 - - 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. - - If you are already familiar with LPD or another printer spooling - system, you may wish to skip to section Setting up the spooling - system. - - - What the Spooler Does - - LPD controls everything about a host's printers. It is responsible - for a number of things: - - - - It controls access to attached printers and printers attached to - other hosts on the network. - - - - It enables users to submit files to be printed; these - submissions are known as jobs. - - - - It prevents multiple users from accessing a printer at the same - time by maintaining a queue for each - printer. - - - - It can print header pages (also known as - banner or burst pages) so - users can easily find jobs they have printed in a stack of - printouts. - - - - It takes care of communications parameters for printers - connected on serial ports. - - - - It can send jobs over the network to another LPD spooler on - another host. - - - - It can run special filters to format jobs to be printed for - various printer languages or printer capabilities. - - - - It can account for printer usage. - - - - 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. - - - - Why You Should Use the Spooler - - 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 - - - - LPD prints jobs in the background; you do not have to wait for - data to be copied to the printer. - - - - 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. - - - - 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. - - - - - - Setting Up the Spooling System - - 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: - - - - See section Simple Printer - Setup to learn how to connect a printer, tell LPD how to - communicate with it, and print plain text files to the - printer. - - - - See section Advanced Printer - Setup 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. - - - - - - Simple Printer Setup - - This section tells how to configure printer hardware and the LPD - software to use the printer. It teaches the basics: - - - - Section Hardware Setup - gives some hints on connecting the printer to a port on your - computer. - - - - Section Software Setup - shows how to setup the LPD spooler configuration file - /etc/printcap. - - - - 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 - Printers With Networked - Data Stream Interaces. - - 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. - - - Hardware Setup - - 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. - - If you have already connected your printer and have successfully - printed with it under another operating system, you can probably skip - to section Software - Setup. - - - Ports and Cables - - Nearly all printers you can get for a PC today support one or - both of the following interfaces: - - - - Serial 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. - - - - Parallel 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. - - Parallel interfaces are sometimes known as - “Centronics” interfaces, named after the connector - type on the printer. - - - - 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. - - 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. - - So, which interface should you use? - - - - If you need two-way communication, use a serial port. - FreeBSD does not yet support two-way communication over a - parallel port. - - - - 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. - - - - Finally, use whatever works. - - - - - - Parallel Ports - - 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. - - Remember which parallel port you used on the computer. The - first parallel port is /dev/lpt0 to FreeBSD; - the second is /dev/lpt1, and so on. - - - - Serial Ports - - 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. - - If you are unsure what the “proper serial cable” is, - you may wish to try one of the following alternatives: - - - - A modem 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. - - - - A null-modem 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. - - - - A serial printer cable, required for - some unusual printers, is like the null modem cable, but sends - some signals to their counterparts instead of being internally - shorted. - - - - 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 - baud rate) 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. - - - - - Software Setup - - This section describes the software setup necessary to print - with the LPD spooling system in FreeBSD. - - Here is an outline of the steps involved: - - - - Configure your kernel, if necessary, for the port you are - using for the printer; section Kernel Configuration tells you - what you need to do. - - - - Set the communications mode for the parallel port, if you are - using a parallel port; section Setting the Communication - Mode for the Parallel Port gives details. - - - - Test if the operating system can send data to the printer. - Section Checking Printer - Communications gives some suggestions on how to do - this. - - - - Set up LPD for the printer by modifying the file - /etc/printcap. Section The /etc/printcap File shows - you how. - - - - - Kernel Configuration - - 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. - - To find out if the kernel you are currently using supports a - serial interface, type: - - &prompt.root; dmesg | grep sioN - - Where N is the number of the serial - port, starting from zero. If you see output similar to the - following: - - sio2 at 0x3e8-0x3ef irq 5 on isa -sio2: type 16550A - - then the kernel supports the port. - - To find out if the kernel supports a parallel interface, - type: - - &prompt.root; dmesg | grep lptN - - Where N is the number of the parallel - port, starting from zero. If you see output similar to the - following lpt0 at 0x378-0x37f on isa then the - kernel supports the port. - - 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. - - To add support for a serial port, see the section on kernel - configuration. To add support for a parallel port, see that section - and the section that follows. - - - Adding <filename>/dev</filename> Entries for the Ports - - 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 /dev - directory are for. - - To add a /dev entry for a - port: - - - - Become root with the &man.su.1; command. Enter the root - password when prompted. - - - - Change to the /dev directory: - - &prompt.root; cd /dev - - - - - Type: - - &prompt.root; ./MAKEDEV port - - Where port is the device entry - for the port you want to make. Use lpt0 - for the first parallel port, lpt1 for the - second, and so on; use ttyd0 for the first - serial port, ttyd1 for the second, and so - on. - - - - Type: - - &prompt.root; ls -l port - - to make sure the device entry got created. - - - - - - Setting the Communication Mode for the Parallel Port - - When you are using the parallel interface, you can choose - whether FreeBSD should use interrupt-driven or polled - communication with the printer. - - - - The interrupt-driven 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. - - - - The polled 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. - - - - The interrupt-driven method is somewhat faster but uses up a - precious IRQ line. You should use whichever one works. - - You can set the communications mode in two ways: by - configuring the kernel or by using the &man.lptcontrol.8; - program. - - To set the communications mode by configuring the - kernel: - - - - Edit your kernel configuration file. Look for or add an - lpt0 entry. If you are setting up the - second parallel port, use lpt1 instead. - Use lpt2 for the third port, and so - on. - - - - If you want interrupt-driven mode, add the - irq specifier: - - -device lpt0 at isa? port? tty irq N vector lptintr - - Where N is the IRQ number - for your computer's parallel port. - - - - If you want polled mode, do not add the - irq specifier: - - -device lpt0 at isa? port? tty vector lptintr - - - - - - Save the file. Then configure, build, and install the - kernel, then reboot. See kernel - configuration for more details. - - - - To set the communications mode with - &man.lptcontrol.8;: - - - - Type: - - &prompt.root; lptcontrol -i -u N - - to set interrupt-driven mode for - lptN. - - - - Type: - - &prompt.root; lptcontrol -p -u N - - to set polled-mode for - lptN. - - - - You could put these commands in your - /etc/rc.local file to set the mode each time - your system boots. See &man.lptcontrol.8; for more - information. - - - - Checking Printer Communications - - 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. - - 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. - - 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: - - -%!PS -100 100 moveto 300 300 lineto stroke -310 310 moveto /Helvetica findfont 12 scalefont setfont -(Is this thing working?) show -showpage - - - 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. - - - - Checking a Parallel Printer - - This section tells you how to check if FreeBSD can - communicate with a printer connected to a parallel port. - - To test a printer on a parallel - port: - - - - Become root with &man.su.1;. - - - - Send data to the printer. - - - - If the printer can print plain text, then use - &man.lptest.1;. Type: - - &prompt.root; lptest > /dev/lptN - - Where N is the number of - the parallel port, starting from zero. - - - - If the printer understands PostScript or other - printer language, then send a small program to the - printer. Type: - - &prompt.root; cat > /dev/lptN - - Then, line by line, type the program - carefully 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. - - Alternatively, you can put the program in a file and - type: - - &prompt.root; cat file > /dev/lptN - - Where file is the name of - the file containing the program you want to send to the - printer. - - - - - - You should see something print. Do not worry if the text - does not look right; we will fix such things later. - - - - Checking a Serial Printer - - This section tells you how to check if FreeBSD can - communicate with a printer on a serial port. - - To test a printer on a serial - port: - - - - Become root with &man.su.1;. - - - - Edit the file /etc/remote. Add the - following entry: - - -printer:dv=/dev/port:br#bps-rate:pa=parity - - Where port is the device - entry for the serial port (ttyd0, - ttyd1, etc.), - bps-rate is the bits-per-second - rate at which the printer communicates, and - parity is the parity required by - the printer (either even, - odd, none, or - zero). - - Here is a sample entry for a printer connected via a - serial line to the third serial port at 19200 bps with no - parity: - - -printer:dv=/dev/ttyd2:br#19200:pa=none - - - - Connect to the printer with &man.tip.1;. Type: - - &prompt.root; tip printer - - If this step does not work, edit the file - /etc/remote again and try using - /dev/cuaaN - instead of - /dev/ttydN. - - - - Send data to the printer. - - - - If the printer can print plain text, then use - &man.lptest.1;. Type: - - ~$lptest - - - - If the printer understands PostScript or other - printer language, then send a small program to the - printer. Type the program, line by line, very - carefully 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. - - Alternatively, you can put the program in a file and - type: - - ~>file - - Where file is the name of - the file containing the program. After - &man.tip.1; sends the file, press any required - end-of-file key. - - - - - - You should see something print. Do not worry if the text - does not look right; we will fix that later. - - - - - - Enabling the Spooler: The <filename>/etc/printcap</filename> - File - - 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. - - You configure LPD by editing the file - /etc/printcap. The LPD spooling system reads - this file each time the spooler is used, so updates to the file take - immediate effect. - - The format of the &man.printcap.5; file is straightforward. Use - your favorite text editor to make changes to - /etc/printcap. The format is identical to - other capability files like - /usr/share/misc/termcap and - /etc/remote. For complete information about - the format, see the &man.cgetent.3;. - - The simple spooler configuration consists of the following - steps: - - - - Pick a name (and a few convenient aliases) for the printer, - and put them in the /etc/printcap file; see - Naming the - Printer. - - - - Turn off header pages (which are on by default) by inserting - the sh capability; see Suppressing Header - Pages. - - - - Make a spooling directory, and specify its location with the - sd capability; see Making the Spooling - Directory. - - - - Set the /dev entry to use for the - printer, and note it in /etc/printcap with - the lp capability; see Identifying the Printer - Device. Also, if the printer is on a serial port, set - up the communication parameters with the fs, - fc, xs, and - xc capabilities; see Configuring Spooler - Communications Parameters. - - - - Install a plain text input filter; see Installing the Text - Filter - - - - Test the setup by printing something with the - &man.lpr.1; command; see Trying It Out and Troubleshooting. - - - - - 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. - - - 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 and 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 Accommodating Plain Text - Jobs on PostScript Printers tells how to do this. - - - Naming the Printer - - 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. - - At least one of the printers specified in the - /etc/printcap should have the alias - lp. This is the default printer's name. If - users do not have the PRINTER environment variable - nor specify a printer name on the command line of any of the LPD - commands, then lp will be the default printer - they get to use. - - Also, it is common practice to make the last alias for a - printer be a full description of the printer, including make and - model. - - Once you have picked a name and some common aliases, put them - in the /etc/printcap 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. - - In the following example, we start with a skeletal - /etc/printcap that defines two printers (a - Diablo 630 line printer and a Panasonic KX-P4455 PostScript laser - printer): - - -# -# /etc/printcap for host rose -# -rattan|line|diablo|lp|Diablo 630 Line Printer: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4: - - In this example, the first printer is named - rattan and has as aliases - line, diablo, - lp, and Diablo 630 Line - Printer. Since it has the alias - lp, it is also the default printer. The second - is named bamboo, and has as aliases - ps, PS, - S, panasonic, and - Panasonic KX-P4455 PostScript v51.4. - - - - Suppressing Header Pages - - The LPD spooling system will by default print a - header page 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. - - To suppress header pages, add the sh - capability to the entry for the printer in - /etc/printcap. Here is the example - /etc/printcap with sh - added: - - -# -# /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: - - 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. - - - - Making the Spooling Directory - - The next step in the simple spooler setup is to make a - spooling directory, a directory where print - jobs reside until they are printed, and where a number of other - spooler support files live. - - Because of the variable nature of spooling directories, it is - customary to put these directories under - /var/spool. It is not necessary to backup - the contents of spooling directories, either. Recreating them is - as simple as running &man.mkdir.1;. - - It is also customary to make the directory with a name that is - identical to the name of the printer, as shown below: - - &prompt.root; mkdir /var/spool/printer-name - - 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 rattan and - bamboo: - - &prompt.root; mkdir /var/spool/lpd -&prompt.root; mkdir /var/spool/lpd/rattan -&prompt.root; mkdir /var/spool/lpd/bamboo - - - 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: - - &prompt.root; chown daemon.daemon /var/spool/lpd/rattan -&prompt.root; chown daemon.daemon /var/spool/lpd/bamboo -&prompt.root; chmod 770 /var/spool/lpd/rattan -&prompt.root; chmod 770 /var/spool/lpd/bamboo - - - Finally, you need to tell LPD about these directories using - the /etc/printcap file. You specify the - pathname of the spooling directory with the sd - capability: - - -# -# /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: - - 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. - - If you do not specify a spooling directory with - sd, the spooling system will use - /var/spool/lpd as a default. - - - - Identifying the Printer Device - - In section Adding /dev - Entries for the Ports, we identified which entry in the - /dev 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). - - List the /dev entry pathname in the - /etc/printcap file using the - lp capability. - - In our running example, let us assume that - rattan is on the first parallel port, and - bamboo is on a sixth serial port; here are the - additions to /etc/printcap: - - -# -# /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: - - If you do not specify the lp capability for - a printer in your /etc/printcap file, LPD - uses /dev/lp as a default. - /dev/lp currently does not exist in - FreeBSD. - - If the printer you are installing is connected to a parallel - port, skip to the section Installing the Text Filter. - Otherwise, be sure to follow the instructions in the next - section. - - - - Configuring Spooler Communication Parameters - - 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: - - - - It lets you try different communication parameters by - simply editing the /etc/printcap file; - you do not have to recompile the filter program. - - - - It enables the spooling system to use the same filter - program for multiple printers which may have different serial - communication settings. - - - - The following /etc/printcap capabilities - control serial communication parameters of the device listed in - the lp capability: - - - - br#bps-rate - - - Sets the communications speed of the device to - bps-rate, where - bps-rate can be 50, 75, 110, 134, - 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, or - 38400 bits-per-second. - - - - - fc#clear-bits - - - Clears the flag bits - clear-bits in the - sgttyb structure after opening - the device. - - - - - fs#set-bits - - - Sets the flag bits set-bits - in the sgttyb structure. - - - - - xc#clear-bits - - - Clears local mode bits - clear-bits after opening the - device. - - - - - xs#set-bits - - - Sets local mode bits - set-bits. - - - - - For more information on the bits for the - fc, fs, - xc, and xs capabilities, see - the file - /usr/include/sys/ioctl_compat.h. - - When LPD opens the device specified by the - lp capability, it reads the flag bits in the - sgttyb structure; it clears any bits in the - fc capability, then sets bits in the - fs capability, then applies the resultant - setting. It does the same for the local mode bits as well. - - 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: - - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:fs#0x82000c1:xs#0x820: - - - - Installing the Text Filter - - We are now ready to tell LPD what text filter to use to send - jobs to the printer. A text filter, also - known as an input filter, 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 lp 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 Filters. - - For our simple printer setup, the text filter can be a small - shell script that just executes /bin/cat to - send the job to the printer. FreeBSD comes with another filter - called lpf 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 lpf is described - in detail in section lpf: a - Text Filter. - - First, let us make the shell script - /usr/local/libexec/if-simple be a simple text - filter. Put the following text into that file with your favorite - text editor: - - -#!/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 - - Make the file executable: - - &prompt.root; chmod 555 /usr/local/libexec/if-simple - - And then tell LPD to use it by specifying it with the - if capability in - /etc/printcap. We will add it to the two - printers we have so far in the example - /etc/printcap: - - -# -# /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: - - - - Trying It Out - - 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. - - You can combine &man.lpr.1; with the &man.lptest.1; program, - introduced in section Checking - Printer Communications to generate some test text. - - To test the simple LPD setup: - - Type: - - &prompt.root; lptest 20 5 | lpr -Pprinter-name - - Where printer-name is a the name of - a printer (or an alias) specified in - /etc/printcap. To test the default printer, - type &man.lpr.1; without any - 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 lpr - file. - - 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: - - -!"#$%&'()*+,-./01234 -"#$%&'()*+,-./012345 -#$%&'()*+,-./0123456 -$%&'()*+,-./01234567 -%&'()*+,-./012345678 - - To further test the printer, try downloading larger programs - (for language-based printers) or running &man.lptest.1; with - different arguments. For example, lptest 80 60 - will produce 60 lines of 80 characters each. - - If the printer did not work, see the next section, Troubleshooting. - - - - Troubleshooting - - After performing the simple test with &man.lptest.1;, you - might have gotten one of the following results instead of the - correct printout: - - - - It worked, after awhile; or, it did not eject a full - sheet. - - - 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. - - 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. - - The following replacement for the shell script - /usr/local/libexec/if-simple prints a - form feed after it sends the job to the printer: - - -#!/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 - - - - - It produced the “staircase effect.” - - - You got the following on paper: - - -!"#$%&'()*+,-./01234 - "#$%&'()*+,-./012345 - #$%&'()*+,-./0123456 - - You have become another victim of the - staircase effect, 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 - and ASCII code 13 (the carriage return - or CR). Many printers use the MS-DOS convention for - representing new-lines. - - 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. - - Here is what FreeBSD wants your printer to do: - - - - - - Printer received CR - Printer prints CR - - - - Printer received LF - Printer prints CR + LF - - - - - - Here are some ways to achieve this: - - - - 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. - - - If you boot your system into other operating - systems besides FreeBSD, you may have to - reconfigure 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. - - - - - Have FreeBSD's serial line driver automatically - convert LF to CR+LF. Of course, this works with - printers on serial ports only. To - enable this feature, set the CRMOD bit in - fs capability in the - /etc/printcap file for the - printer. - - - - Send an escape code 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. - - 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. - - -#!/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 - - Here is an example - /etc/printcap from a host called - orchid. It has a single printer attached to its first - parallel port, a Hewlett Packard LaserJet 3Si named - teak. It is using the above script as - its text filter: - - -# -# /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: - - - - - - - It overprinted each line. - - - The printer never advanced a line. All of the lines of - text were printed on top of each other on one line. - - 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. - - Use the printer's configuration switches or control - panel to enforce the following interpretation of LF and CR - characters: - - - - - - Printer receives - Printer prints - - - - - - CR - CR - - - - LF - CR + LF - - - - - - - - The printer lost characters. - - - 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. - - 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: - - - - If the printer supports XON/XOFF flow control, have - FreeBSD use it by specifying the TANDEM bit in the - fs capability. - - - - If the printer supports carrier flow control, - specify the MDMBUF bit in the fs - capability. Make sure the cable connecting the printer - to the computer is correctly wired for carrier flow - control. - - - - If the printer does not support any flow control, - use some combination of the NLDELAY, TBDELAY, CRDELAY, - VTDELAY, and BSDELAY bits in the fs - capability to add appropriate delays to the stream of - data sent to the printer. - - - - - - - It printed garbage. - - - The printer printed what appeared to be random garbage, - but not the desired text. - - This is usually another symptom of incorrect - communications parameters with a serial printer. - Double-check the bps rate in the br - capability, and the parity bits in the fs - and fc capabilities; make sure the - printer is using the same settings as specified in the - /etc/printcap file. - - - - - Nothing happened. - - - If nothing happened, the problem is probably within - FreeBSD and not the hardware. Add the log file - (lf) capability to the entry for the - printer you are debugging in the - /etc/printcap file. For example, here - is the entry for rattan, with the - lf capability: - - -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 - - Then, try printing again. Check the log file (in our - example, /var/log/rattan.log) to see - any error messages that might appear. Based on the messages - you see, try to correct the problem. - - If you do not specify a lf - capability, LPD uses /dev/console as a - default. - - - - - - - - - - Using Printers - - This section tells you how to use printers you have setup with - FreeBSD. Here is an overview of the user-level commands: - - - - &man.lpr.1; - - - Print jobs - - - - - &man.lpq.1; - - - Check printer queues - - - - - &man.lprm.1; - - - Remove jobs from a printer's queue - - - - - There is also an administrative command, &man.lpc.8;, described in - the section Administrating the LPD - Spooler, used to control printers and their queues. - - All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1; - accept an option to specify on which - printer/queue to operate, as listed in the - /etc/printcap file. This enables you to submit, - remove, and check on jobs for various printers. If you do not use the - option, then these commands use the printer - specified in the PRINTER environment variable. Finally, - if you do not have a PRINTER environment variable, these - commands default to the printer named lp. - - Hereafter, the terminology default printer - means the printer named in the PRINTER environment - variable, or the printer named lp when there is no - PRINTER environment variable. - - - Printing Jobs - - To print files, type: - - &prompt.user; lpr filename ... - - 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: - - &prompt.user; lpr /etc/host.conf /etc/hosts.equiv - - To select a specific printer, type: - - &prompt.user; lpr -P printer-name filename ... - - This example prints a long listing of the current directory to the - printer named rattan: - - &prompt.user; ls -l | lpr -P rattan - - Because no files were listed for the - &man.lpr.1; command, lpr read the data to print - from standard input, which was the output of the ls - -l command. - - 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 Printing Options. - - - - Checking Jobs - - 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. - - To display the queue for the default printer, type &man.lpq.1;. - For a specific printer, use the option. For - example, the command - - &prompt.user; lpq -P bamboo - - shows the queue for the printer named bamboo. Here - is an example of the output of the lpq - command: - - 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 - - This shows three jobs in the queue for bamboo. - 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 Removing Jobs for details. - - 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 active - 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 mary; 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. - - 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). - - The &man.lpq.1; command also support a option - to generate a detailed long listing. Here is an example of - lpq -l: - - 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 - - - - Removing Jobs - - 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. - - To remove a job from the default printer, first use - &man.lpq.1; to find the job number. Then type: - - &prompt.user; lprm job-number - - To remove the job from a specific printer, add the - option. The following command removes job number - 10 from the queue for the printer bamboo: - - &prompt.user; lprm -P bamboo 10 - - The &man.lprm.1; command has a few shortcuts: - - - - lprm - - - - Removes all jobs (for the default printer) belonging to - you. - - - - - lprm user - - - Removes all jobs (for the default printer) belonging to - user. The superuser can remove other - users' jobs; you can remove only your own jobs. - - - - - lprm - - - With no job number, user name, or - 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. - - - - - Just use the 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 rattan: - - &prompt.user; lprm -P rattan - - - - 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: - - &prompt.user; lpr -P rattan myfile -&prompt.user; rlogin orchid -&prompt.user; lpq -P rattan -Rank Owner Job Files Total Size -active seeyan 12 ... 49123 bytes -2nd kelly 13 myfile 12 bytes -&prompt.user; lprm -P rattan 13 -rose: Permission denied -&prompt.user; logout -&prompt.user; lprm -P rattan 13 -dfA013rose dequeued -cfA013rose dequeued - - - - - - Beyond Plain Text: Printing Options - - 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. - - - Formatting and Conversion Options - - 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. - - For example, the following command prints a DVI file (from the - TeX typesetting system) named fish-report.dvi - to the printer named bamboo: - - &prompt.user; lpr -P bamboo -d fish-report.dvi - - 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. - - - All of these options except and - require conversion filters installed for the - destination printer. For example, the option - requires the DVI conversion filter. Section Conversion - Filters gives details. - - - - - - - - Print cifplot files. - - - - - - - - Print DVI files. - - - - - - - - Print FORTRAN text files. - - - - - - - - Print plot data. - - - - - - - - Indent the output by number - columns; if you omit number, indent - by 8 columns. This option works only with certain conversion - filters. - - - Do not put any space between the and - the number. - - - - - - - - - Print literal text data, including control - characters. - - - - - - - - Print ditroff (device independent troff) data. - - - - - -p - - - Format plain text with &man.pr.1; before printing. See - &man.pr.1; for more information. - - - - - - - - Use title on the - &man.pr.1; header instead of the file name. This option has - effect only when used with the - option. - - - - - - - - Print troff data. - - - - - - - - Print raster data. - - - - - Here is an example: this command prints a nicely formatted - version of the &man.ls.1; manual page on the default printer: - - &prompt.user; zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t - - The &man.zcat.1; command uncompresses the source of the - - &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 to - - &man.lpr.1;, the spooler will convert the GNU troff output into - a format the default printer can understand when it prints the - job. - - - - Job Handling Options - - The following options to &man.lpr.1; tell LPD to handle the job - specially: - - - - -# copies - - - Produce a number of copies 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 - Restricting - Multiple Copies. - - This example prints three copies of - parser.c followed by three copies of - parser.h to the default printer: - - &prompt.user; lpr -#3 parser.c parser.h - - - - - -m - - - 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. - - - - - -s - - - Do not copy the files to the spooling directory, but make - symbolic links to them instead. - - 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. - - 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. - - - 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 will save - space only on the local spooling directory, not the remote. - It is still useful, though. - - - - - - -r - - - Remove the files in the job after copying them to the - spooling directory, or after printing them with the - option. Be careful with this - option! - - - - - - - Header Page Options - - 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 - Header Pages - for information about setting up header pages. - - - - -C text - - - Replace the hostname on the header page with - text. The hostname is normally the - name of the host from which the job was submitted. - - - - - -J text - - - Replace the job name on the header page with - text. The job name is normally the - name of the first file of the job, or - stdin if you are printing standard - input. - - - - - -h - - - Do not print any header page. - - - At some sites, this option may have no effect due to the - way header pages are generated. See Header - Pages for details. - - - - - - - - - Administrating Printers - - 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 - - - - Start and stop the printers - - - - Enable and disable their queues - - - - Rearrange the order of the jobs in each queue. - - - - First, a note about terminology: if a printer is - stopped, it will not print anything in its queue. - Users can still submit jobs, which will wait in the queue until the - printer is started or the queue is - cleared. - - If a queue is disabled, no user (except root) - can submit jobs for the printer. An enabled - queue allows jobs to be submitted. A printer can be - started for a disabled queue, in which case it - will continue to print jobs in the queue until the queue is - empty. - - 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. - - Here is a summary of the &man.lpc.8; commands. Most of the - commands takes a printer-name argument to - tell on which printer to operate. You can use all - for the printer-name to mean all printers - listed in /etc/printcap. - - - - abort - printer-name - - - Cancel the current job and stop the printer. Users can - still submit jobs if the queue's enabled. - - - - - clean - printer-name - - - 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. - - - - - disable - printer-name - - - 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. - - 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 - enable command. - - - - - down printer-name - message - - - Take a printer down. Equivalent to - disable followed by stop. - The message appears as the printer's - status whenever a user checks the printer's queue with - &man.lpq.1; or status with lpc - status. - - - - - enable - printer-name - - - Enable the queue for a printer. Users can submit jobs but - the printer will not print anything until it is started. - - - - - help - command-name - - - Print help on the command - command-name. With no - command-name, print a summary of the - commands available. - - - - - restart - printer-name - - - 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 stop or - down commands. The - restart command is equivalent to - abort followed by - start. - - - - - start - printer-name - - - Start the printer. The printer will print jobs in its - queue. - - - - - stop - printer-name - - - 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. - - - - - topq printer-name - job-or-username - - - Rearrange the queue for - printer-name by placing the jobs with - the listed job numbers or the jobs - belonging to username at the top of - the queue. For this command, you cannot use - all as the - printer-name. - - - - - up - printer-name - - - Bring a printer up; the opposite of the - down command. Equivalent to - start followed by - enable. - - - - - &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 exit, - quit, or end-of-file. - - - - - Advanced Printer Setup - - This section describes filters for printing specially formatted - files, header pages, printing across networks, and restricting and - accounting for printer usage. - - - Filters - - Although LPD handles network protocols, queuing, access control, - and other aspects of printing, most of the real - work happens in the filters. 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 Installing the Text - Filter). - - 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 - you have to provide filters yourself. The good - news is that many are generally available; when they are not, they are - usually easy to write. - - Also, FreeBSD comes with one, - /usr/libexec/lpr/lpf, 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. - - Here is what you will find in this section: - - - - Section How Filters - Work, 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. - - - - 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 Accommodating - Plain Text Jobs on PostScript Printers tells you what you - should do to overcome this problem. I recommend reading this - section if you have a PostScript printer. - - - - PostScript is a popular output format for many programs. Even - some people (myself included) write PostScript code directly. But - PostScript printers are expensive. Section Simulating PostScript on - Non-PostScript Printers tells how you can further modify - a printer's text filter to accept and print PostScript data on a - non-PostScript printer. I recommend reading - this section if you do not have a PostScript printer. - - - - Section Conversion - Filters 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 lpr -t to print troff data, or - lpr -d to print TeX DVI data, or lpr - -v to print raster image data, and so forth. I - recommend reading this section. - - - - Section Output - Filters tells all about a not often used feature of LPD: - output filters. Unless you are printing header pages (see Header Pages), - you can probably skip that section altogether. - - - - Section lpf: a Text - Filter describes lpf, 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 - lpf. - - - - - How Filters Work - - As mentioned before, a filter is an executable program started - by LPD to handle the device-dependent part of communicating with the - printer. - - 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 lf - capability in /etc/printcap, or - /dev/console by default). - - Which filter LPD starts and the filter's arguments depend on - what is listed in the /etc/printcap file and - what arguments the user specified for the job on the - &man.lpr.1; command line. For example, if the user typed - lpr -t, LPD would start the troff filter, listed - in the tf capability for the destination printer. - If the user wanted to print plain text, it would start the - if filter (this is mostly true: see Output Filters for - details). - - There are three kinds of filters you can specify in - /etc/printcap: - - - - The text filter, confusingly called the - input filter 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: - - - filter-name - -c - -wwidth - -llength - -iindent - -n login - -h host - acct-file - - - where - - - - - - - appears if the job's submitted with lpr - -l - - - - - width - - - is the value from the pw (page - width) capability specified in - /etc/printcap, default 132 - - - - - length - - - is the value from the pl (page - length) capability, default 66 - - - - - indent - - - is the amount of the indentation from lpr - -i, default 0 - - - - - login - - - is the account name of the user printing the - file - - - - - host - - - is the host name from which the job was - submitted - - - - - acct-file - - - is the name of the accounting file from the - af capability. - - - - - - - - A conversion filter 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 Conversion - Filters tells all about them. Conversion filters also - need to do accounting, if you need printer accounting. - Conversion filters are started with the following arguments: - - - filter-name - -xpixel-width - -ypixel-height - -n login - -h host - acct-file - - - where pixel-width is the value - from the px capability (default 0) and - pixel-height is the value from the - py capability (default 0). - - - - The output filter is used only if there - is no text filter, or if header pages are enabled. In my - experience, output filters are rarely used. Section Output Filters describe - them. There are only two arguments to an output filter: - - - filter-name - -wwidth - -llength - - - which are identical to the text filters and - arguments. - - - - Filters should also exit with the - following exit status: - - - - exit 0 - - - If the filter printed the file successfully. - - - - - exit 1 - - - 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. - - - - - exit 2 - - - If the filter failed to print the file and does not want - LPD to try again. LPD will throw out the file. - - - - - The text filter that comes with the FreeBSD release, - /usr/libexec/lpr/lpf, 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. - - 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. - - - - Accommodating Plain Text Jobs on PostScript Printers - - 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. - - 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 - %! (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. - - How do we do this? - - If you have got a serial printer, a great way to do it is to - install lprps. lprps 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 toner - low or paper jam). But more - importantly, it includes a program called psif - which detects whether the incoming job is plain text and calls - textps (another program that comes with - lprps) to convert it to PostScript. It then uses - lprps to send the job to the printer. - - lprps is part of the FreeBSD ports collection - (see The Ports Collection). You can - fetch, build and install it yourself, of course. After installing - lprps, just specify the pathname to the - psif program that is part of - lprps. If you installed lprps - from the ports collection, use the following in the serial - PostScript printer's entry in - /etc/printcap: - - -:if=/usr/local/libexec/psif: - - You should also specify the rw capability; - that tells LPD to open the printer in read-write mode. - - If you have a parallel PostScript printer (and therefore cannot - use two-way communication with the printer, which - lprps needs), you can use the following shell - script as the text filter: - - -#!/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 - - In the above script, textps 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 The Ports Collection) - includes a full featured text-to-PostScript program called - a2ps that you might want to investigate. - - - - Simulating PostScript on Non-PostScript Printers - - PostScript is the de facto standard for - high quality typesetting and printing. PostScript is, however, an - expensive standard. Thankfully, Alladin - Enterprises has a free PostScript work-alike called - Ghostscript 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. - - 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. - - 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. - - Here is an example: the following script is a text filter - for Hewlett Packard DeskJet 500 printers. For other printers, - substitute the argument to the - gs (Ghostscript) command. (Type gs - -h to get a list of devices the current installation of - Ghostscript supports.) - - -#!/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 - - Finally, you need to notify LPD of the filter via the - if capability: - - -:if=/usr/local/libexec/hpif: - - That is it. You can type lpr plain.text and - lpr whatever.ps and both should print - successfully. - - - - Conversion Filters - - After completing the simple setup described in Simple Printer Setup, the first - thing you will probably want to do is install conversion filters for - your favorite file formats (besides plain ASCII text). - - - Why Install Conversion Filters? - - 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: - - &prompt.user; dvips seaweed-analysis.dvi -&prompt.user; lpr seaweed-analysis.ps - - 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: - - &prompt.user; lpr -d seaweed-analysis.dvi - - We got LPD to do the DVI file conversion for us by specifying - the option. Section Formatting and Conversion - Options lists the conversion options. - - For each of the conversion options you want a printer to - support, install a conversion filter and - specify its pathname in /etc/printcap. A - conversion filter is like the text filter for the simple printer - setup (see section Installing - the Text Filter) except that instead of printing plain - text, the filter converts the file into a format the printer can - understand. - - - - Which Conversions Filters Should I Install? - - 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. - - The following table summarizes the filters that LPD works - with, their capability entries for the - /etc/printcap file, and how to invoke them - with the lpr command: - - - - - - File type - /etc/printcap capability - lpr option - - - - - - cifplot - cf - - - - - DVI - df - - - - - plot - gf - - - - - ditroff - nf - - - - - FORTRAN text - rf - - - - - troff - rf - - - - - raster - vf - - - - - plain text - if - none, , or - - - - - - - In our example, using lpr -d means the - printer needs a df capability in its entry in - /etc/printcap. - - 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 - gf capability and then educate your users that - lpr -g mean “print Printerleaf - files.” - - - - Installing Conversion Filters - - Since conversion filters are programs you install outside of - the base FreeBSD installation, they should probably go under - /usr/local. The directory - /usr/local/libexec is a popular location, - since they are specialized programs that only LPD will run; - regular users should not ever need to run them. - - To enable a conversion filter, specify its pathname under the - appropriate capability for the destination printer in - /etc/printcap. - - In our example, we will add the DVI conversion filter to the - entry for the printer named bamboo. Here is - the example /etc/printcap file again, with - the new df capability for the printer - bamboo. - - -# -# /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: - - The DVI filter is a shell script named - /usr/local/libexec/psdf. Here is that - script: - - -#!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 "$@" - - This script runs dvips in filter mode (the - argument) on standard input, which is the job - to print. It then starts the PostScript printer filter - lprps (see section Accommodating Plain - Text Jobs on PostScript Printers) with the arguments LPD - passed to this script. lprps will use those - arguments to account for the pages printed. - - - - More Conversion Filter Examples - - 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. - - This example script is a raster (well, GIF file, actually) - conversion filter for a Hewlett Packard LaserJet III-Si - printer: - - -#!/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 - - 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. - - Here is the /etc/printcap file with an - entry for a printer using the above filter: - - -# -# /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: - - The following script is a conversion filter for troff data - from the groff typesetting system for the PostScript printer named - bamboo: - - -#!/bin/sh -# -# pstf - Convert groff's troff data into PS, then print. -# Installed in /usr/local/libexec/pstf -# -exec grops | /usr/local/libexec/lprps "$@" - - The above script makes use of lprps again - to handle the communication with the printer. If the printer were - on a parallel port, we would use this script instead: - - -#!/bin/sh -# -# pstf - Convert groff's troff data into PS, then print. -# Installed in /usr/local/libexec/pstf -# -exec grops - - That is it. Here is the entry we need to add to - /etc/printcap to enable the filter: - - -:tf=/usr/local/libexec/pstf: - - 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 - teak: - - -#!/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 - - And we will add this line to the - /etc/printcap for the printer - teak to enable this filter: - - -:rf=/usr/local/libexec/hprf: - - Here is one final, somewhat complex example. We will add a - DVI filter to the LaserJet printer teak - introduced earlier. First, the easy part: updating - /etc/printcap with the location of the DVI - filter: - - -:df=/usr/local/libexec/hpdf: - - Now, for the hard part: making the filter. For that, we need - a DVI-to-LaserJet/PCL conversion program. The FreeBSD ports - collection (see The Ports Collection) - has one: dvi2xx is the name of the package. - Installing this package gives us the program we need, - dvilj2p, which converts DVI into LaserJet IIp, - LaserJet III, and LaserJet 2000 compatible codes. - - dvilj2p makes the filter - hpdf quite complex since - dvilj2p cannot read from standard input. It - wants to work with a filename. What is worse, the filename has to - end in .dvi so using - /dev/fd/0 for standard input is problematic. - We can get around that problem by linking (symbolically) a - temporary file name (one that ends in .dvi) - to /dev/fd/0, thereby forcing - dvilj2p to read from standard input. - - The only other fly in the ointment is the fact that we cannot - use /tmp for the temporary link. Symbolic - links are owned by user and group bin. The - filter runs as user daemon. And the - /tmp 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. - - Instead, the filter will make the symbolic link in the current - working directory, which is the spooling directory (specified by - the sd capability in - /etc/printcap). 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 - /tmp. - - Here, finally, is the filter: - - -#!/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 - - - - Automated Conversion: An Alternative To Conversion - Filters - - 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. - - 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 - file can be of help here. Of course, it will - be hard to determine the differences between - some file types—and, of course, you can - still provide conversion filters just for them. - - The FreeBSD ports collection has a text filter that performs - automatic conversion called apsfilter. It can - detect plain text, PostScript, and DVI files, run the proper - conversions, and print. - - - - - Output Filters - - 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: - - - - LPD starts an output filter once for the entire job instead - of once for each file in the job. - - - - LPD does not make any provision to identify the start or the - end of files within the job for the output filter. - - - - 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: - - - filter-name - -wwidth - -llength - - - Where width is from the - pw capability and - length is from the - pl capability for the printer in - question. - - - - 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 will not work. Use a text filter (also - known as an input filter); see section Installing the Text Filter. - Furthermore, an output filter is actually more - complex 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. - - However, an output filter is necessary 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 futile 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.) - - 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 Header Pages) - only. LPD then expects the output filter to stop - itself 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. - - If there is an output filter but no 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 - not what you want. In almost all cases, you - need a text filter. - - The program lpf, 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 lpf. You - can also wrap lpf in a shell script to handle any - initialization codes the printer might require. - - - - <command>lpf</command>: a Text Filter - - The program /usr/libexec/lpr/lpf that comes - with FreeBSD binary distribution is a text filter (input filter) - that can indent output (job submitted with lpr - -i), allow literal characters to pass (job submitted - with lpr -l), adjust the printing position for - backspaces and tabs in the job, and account for pages printed. It - can also act like an output filter. - - lpf 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 - lpf. - - In order for lpf to do page accounting - correctly, it needs correct values filled in for the - pw and pl capabilities in the - /etc/printcap 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 Accounting for Printer - Usage. - - - - - Header Pages - - If you have lots of users, all of them using - various printers, then you probably want to consider header - pages as a necessary evil. - - Header pages, also known as banner or - burst pages 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.) - - The LPD system can provide header pages automatically for your - printouts if 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 Header Pages on - PostScript Printers. - - - Enabling Header Pages - - In the Simple Printer - Setup, we turned off header pages by specifying - sh (meaning “suppress header”) in the - /etc/printcap file. To enable header pages for - a printer, just remove the sh capability. - - Sounds too easy, right? - - You are right. You might 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: - - -#!/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 - - Specify the path to the output filter in the - of capability. See Output Filters for more - information. - - Here is an example /etc/printcap file for - the printer teak that we introduced earlier; we - enabled header pages and added the above output filter: - - -# -# /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: - - Now, when users print jobs to teak, 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 lpr -h; see Header Page Options for - more &man.lpr.1; options. - - - 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 ff - capability in /etc/printcap. - - - - - Controlling Header Pages - - By enabling header pages, LPD will produce a long - header, 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): - - - 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 - - LPD appends a form feed after this text so the job starts on a - new page (unless you have sf (suppress form - feeds) in the destination printer's entry in - /etc/printcap). - - If you prefer, LPD can make a short header; - specify sb (short banner) in the - /etc/printcap file. The header page will look - like this: - - -rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 - - Also by default, LPD prints the header page first, then the job. - To reverse that, specify hl (header last) in - /etc/printcap. - - - - Accounting for Header Pages - - Using LPD's built-in header pages enforces a particular paradigm - when it comes to printer accounting: header pages must be - free of charge. - - Why? - - 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 user or - host 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 lpr -h. - They could still be charged for header pages they did not print. - Basically, lpr -h will be the preferred option of - environmentally-minded users, but you cannot offer any incentive to - use it. - - It is still not enough 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 lpr -h, they will still get - them and be charged for them since LPD does not pass any knowledge - of the option to any of the filters. - - So, what are your options? - - You can: - - - - Accept LPD's paradigm and make header pages free. - - - - Install an alternative to LPD, such as LPRng or PLP. Section - Alternatives to the - Standard Spooler tells more about other spooling - software you can substitute for LPD. - - - - Write a smart 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 af 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 - sh (short header) capability in - /etc/printcap. Then again, all that might - be too much trouble, and users will certainly appreciate the - more generous system administrator who makes header pages - free. - - - - - - Header Pages on PostScript Printers - - 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. - - 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 lpr - -h. - - 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: - - -#!/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 - - 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: - - -#!/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 - - 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 How Filters - Work). - - As we have mentioned before, the above scheme, though fairly - simple, disables the “suppress header page” option (the - option) to lpr. 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. - - To allow users to shut off header pages on a per-job basis, you - will need to use the trick introduced in section Accounting for - Header Pages: write an output filter that parses the - LPD-generated header page and produces a PostScript version. If the - user submits the job with lpr -h, 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. - - If you have a PostScript printer on a serial line, you can make - use of lprps, which comes with an output filter, - psof, which does the above. Note that - psof does not charge for header pages. - - - - - Networked Printing - - FreeBSD supports networked printing: sending jobs to remote - printers. Networked printing generally refers to two different - things: - - - - 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 Printers Installed on - Remote Hosts tells how to do this. - - - - 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: - - - - 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 Printers - Installed on Remote Hosts to set up such a - printer. - - - - 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 Printers with - Networked Data Stream Interfaces gives some - suggestions on installing such printers. - - - - - - - Printers Installed on Remote Hosts - - 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. - - To enable this kind of remote printing, first install a printer - on one host, the printer host, using the simple - printer setup described in Simple - Printer Setup. Do any advanced setup in Advanced Printer Setup 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 - local host has authorization to use the LPD - service in the remote host (see Restricting Jobs - from Remote Printers). - - If you are using a printer with a network interface that is - compatible with LPD, then the printer host in - the discussion below is the printer itself, and the - printer name is the name you configured for the - printer. See the documentation that accompanied your printer and/or - printer-network interface. - - Then, on the other hosts you want to have access to the printer, - make an entry in their /etc/printcap files with - the following: - - - - Name the entry anything you want. For simplicity, though, - you probably want to use the same name and aliases as on the - printer host. - - - - Leave the lp capability blank, explicitly - (:lp=:). - - - - Make a spooling directory and specify its location in the - sd capability. LPD will store jobs here - before they get sent to the printer host. - - - - Place the name of the printer host in the - rm capability. - - - - Place the printer name on the printer - host in the rp - capability. - - - - That is it. You do not need to list conversion filters, page - dimensions, or anything else in the - /etc/printcap file. - - Here is an example. The host rose has two - printers, bamboo and rattan. - We will enable users on the host orchid to print to those printers. - Here is the /etc/printcap file for - orchid (back from section Enabling Header - Pages). It already had the entry for the printer - teak; we have added entries for the two printers - on the host rose: - - -# -# /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: - - Then, we just need to make spooling directories on - orchid: - - &prompt.root; mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo -&prompt.root; chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo -&prompt.root; chown daemon.daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo - - Now, users on orchid can print to - rattan and bamboo. If, for - example, a user on orchid typed - - &prompt.user; lpr -P bamboo -d sushi-review.dvi - - the LPD system on orchid would copy the job to the spooling - directory /var/spool/lpd/bamboo and note that - it was a DVI job. As soon as the host rose has room in its - bamboo 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. - - - - Printers with Networked Data Stream Interfaces - - 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 Printers Installed on - Remote Hosts. - - The format of the /etc/printcap 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. - - 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 - netprint 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 netprint. 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.). - - -#!/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; - - 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: - - -#!/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 - - - - - Restricting Printer Usage - - 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. - - - Restricting Multiple Copies - - The LPD system makes it easy for users to print multiple copies - of a file. Users can print jobs with lpr -#5 - (for example) and get five copies of each file in the job. Whether - this is a good thing is up to you. - - If you feel multiple copies cause unnecessary wear and tear on - your printers, you can disable the option to - &man.lpr.1; by adding the sc capability to the - /etc/printcap file. When users submit jobs - with the option, they will see: - - lpr: multiple copies are not allowed - - - Note that if you have set up access to a printer remotely (see - section Printers - Installed on Remote Hosts), you need the - sc capability on the remote - /etc/printcap files as well, or else users will - still be able to submit multiple-copy jobs by using another - host. - - Here is an example. This is the - /etc/printcap file for the host - rose. The printer rattan is - quite hearty, so we will allow multiple copies, but the laser - printer bamboo's a bit more delicate, so we will - disable multiple copies by adding the sc - capability: - - -# -# /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: - - Now, we also need to add the sc capability on - the host orchid's - /etc/printcap (and while we are at it, let us - disable multiple copies for the printer - teak): - - -# -# /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: - - By using the sc capability, we prevent the - use of lpr -#, 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: - - &prompt.user; lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign - - There are many ways to prevent this abuse (including ignoring - it) which you are free to explore. - - - - Restricting Access To Printers - - You can control who can print to what printers by using the UNIX - group mechanism and the rg capability in - /etc/printcap. Just place the users you want - to have access to a printer in a certain group, and then name that - group in the rg capability. - - Users outside the group (including root) will be greeted with - - lpr: Not a member of the restricted group - - if they try to print to the controlled printer. - - As with the sc (suppress multiple copies) - capability, you need to specify rg on remote - hosts that also have access to your printers, if you feel it is - appropriate (see section Printers Installed on - Remote Hosts). - - For example, we will let anyone access the printer - rattan, but only those in group - artists can use bamboo. Here - is the familiar /etc/printcap for host - rose: - - -# -# /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: - - Let us leave the other example - /etc/printcap file (for the host - orchid) alone. Of course, anyone on - orchid can print to bamboo. It - might be the case that we only allow certain logins on - orchid anyway, and want them to have access to the - printer. Or not. - - - There can be only one restricted group per printer. - - - - - Controlling Sizes of Jobs Submitted - - 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. - - LPD enables you to limit the maximum byte size a file in a job - can be with the mx 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 - mx capability is specified, then a default limit - of 1000 blocks will be used. - - - The limit applies to files in a job, and - not the total job size. - - - 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. - - Let us add limits to our example printers - rattan and bamboo. 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: - - -# -# /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: - - 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 mx - capability in the remote /etc/printcap files as - well. See section Printers Installed on - Remote Hosts for more information on remote - printing. - - There is another specialized way to limit job sizes from remote - printers; see section Restricting Jobs - from Remote Printers. - - - - Restricting Jobs from Remote Printers - - The LPD spooling system provides several ways to restrict print - jobs submitted from remote hosts: - - - - Host restrictions - - - You can control from which remote hosts a local LPD - accepts requests with the files - /etc/hosts.equiv and - /etc/hosts.lpd. 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. - - The format of these files is simple: one host name per - line. Note that the file - /etc/hosts.equiv is also used by the - &man.ruserok.3; protocol, and affects programs like - &man.rsh.1; and &man.rcp.1;, so be careful. - - For example, here is the - /etc/hosts.lpd file on the host - rose: - - -orchid -violet -madrigal.fishbaum.de - - This means rose will accept requests from - the hosts orchid, violet, - and madrigal.fishbaum.de. If any - other host tries to access rose's LPD, LPD - will refuse them. - - - - - Size restrictions - - - You can control how much free space there needs to remain - on the filesystem where a spooling directory resides. Make a - file called minfree 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. - - 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 - minfree file. - - For example, let us add a minfree - file for the printer bamboo. We examine - /etc/printcap to find the spooling - directory for this printer; here is bamboo's - entry: - - -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: - - The spooling directory is the given in the - sd 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: - - &prompt.root; echo 6144 > /var/spool/lpd/bamboo/minfree - - - - - User restrictions - - - You can control which remote users can print to local - printers by specifying the rs capability in - /etc/printcap. When - rs appears in the entry for a - locally-attached printer, LPD will accept jobs from remote - hosts if the user submitting the job also - has an account of the same login name on the local host. - Otherwise, LPD refuses the job. - - 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 only your - printers and not your compute resources, you can give them - “token” accounts, with no home directory and a - useless shell like /usr/bin/false. - - - - - - - - Accounting for Printer Usage - - 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? - - 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 - your requirements in charging for printer - usage. - - 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 Filters. - - Generally, there are two ways to do accounting: - - - - Periodic accounting 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. - - - - Timely accounting 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. - - - - 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. - - - Quick and Dirty Printer Accounting - - FreeBSD comes with two programs that can get you set up with - simple periodic accounting right away. They are the text filter - lpf, described in section lpf: a Text Filter, and - &man.pac.8;, a program to gather and total - entries from printer accounting files. - - As mentioned in the section on filters (Filters), 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 af capability in - /etc/printcap, and if not specified as an - absolute path, is relative to the spooling directory. - - LPD starts lpf with page width and length - arguments (from the pw and pl - capabilities). lpf 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: - - -2.00 rose:andy -3.00 rose:kelly -3.00 orchid:mary -5.00 orchid:mary -2.00 orchid:zhang - - You should use a separate accounting file for each printer, as - lpf has no file locking logic built into it, and - two lpfs 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 - af=acct in /etc/printcap. - Then, each accounting file will be in the spooling directory for a - printer, in a file named acct. - - 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 pac. - You will get a dollar-centric summary like the following: - - 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 - - These are the arguments &man.pac.8; expects: - - - - - - - Which printer to summarize. - This option works only if there is an absolute path in the - af capability in - /etc/printcap. - - - - - - - - Sort the output by cost instead of alphabetically by user - name. - - - - - - - - Ignore host name in the accounting files. With this - option, user smith on host - alpha is the same user - smith on host gamma. - Without, they are different users. - - - - - - - - Compute charges with price - dollars per page or per foot instead of the price from the - pc capability in - /etc/printcap, or two cents (the - default). You can specify price as - a floating point number. - - - - - - - - Reverse the sort order. - - - - - - - - Make an accounting summary file and truncate the - accounting file. - - - - - name - … - - - Print accounting information for the given user - names only. - - - - - 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 pac -m, to produce the following - summary: - - 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 - - - To compute the dollar amount due, - &man.pac.8; uses the pc capability in the - /etc/printcap 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. The units for the - option are in dollars, though, not hundredths of cents. For - example, - - &prompt.root; pac -p1.50 - - makes each page cost one dollar and fifty cents. You can really - rake in the profits by using this option. - - Finally, running pac -s will save the summary - information in a summary accounting file, which is named the same as - the printer's accounting file, but with _sum - 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. - - - - How Can You Count Pages Printed? - - 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. - - 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. - - The text filter lpf (introduced in lpf: a Text Filter) 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 lpf's source code. - - How do you handle other file formats, though? - - Well, for DVI-to-LaserJet or DVI-to-PostScript conversion, you - can have your filter parse the diagnostic output of - dvilj or dvips and look to see - how many pages were converted. You might be able to do similar - things with other file formats and conversion programs. - - 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. - - So, what can you do? - - There is only one sure way to do - accurate 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 - only. There is no line counting nor - error-prone file examination required. - - Of course, you can always be generous and make all printouts - free. - - - - - - Alternatives to the Standard Spooler - - 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)?” - - Unfortunately, I have located only two - alternatives—and they are almost identical to each other! They - are: - - - - PLP, the Portable Line Printer Spooler System - - - 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 ftp://ftp.iona.ie/pub/plp. - There is also a web - page. - - It is quite similar to the BSD LPD spooler, but boasts a - host of features, including: - - - - Better network support, including built-in support for - networked printers, NIS-maintained printcaps, and NFS-mounted - spooling directories - - - - Sophisticated queue management, allowing multiple printers - on a queue, transfer of jobs between queues, and queue - redirection - - - - Remote printer control functions - - - - Prioritization of jobs - - - - Expansive security and access options - - - - - - - LPRng - - - 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 ftp://dickory.sdsu.edu/pub/LPRng. - - - - - - - Acknowledgments - - I would like to thank the following people who have assisted in the - development of this document: - - - - Daniel Eischen - deischen@iworks.interworks.org - - - For providing a plethora of HP filter programs for - perusal. - - - - - &a.jehamby; - - - For the Ghostscript-to-HP filter. - - - - - &a.jfieber; - - - 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. - - - - - Stephen Montgomery-Smith - stephen@math.missouri.edu - - - 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. - - - - - My wife, Mary Kelly - urquhart@argyre.colorado.edu - - - For allowing me to spend more time with FreeBSD than - with her. - - - - - - - - - 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 @@ - - - - Disk Quotas - - Contributed by &a.mpp;. 26 February - 1996 - - 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. - - - Configuring Your System to Enable Disk Quotas - - 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: - - -options QUOTA - - The stock GENERIC 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 Configuring the FreeBSD Kernel section - for more information on kernel configuration. - - Next you will need to enable disk quotas in - /etc/sysconfig. This is done by changing the line: - - -quotas=NO - - to: - - -quotas=YES - - If you are running FreeBSD 2.2.2 or later, the configuration file - will be /etc/rc.conf instead and the variable name - changed to: - - -check_quotas=YES - - Finally you will need to edit /etc/fstab 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. - - To enable per-user quotas on a file system, add the - userquota option to the options field in the - /etc/fstab entry for the file system you want to to - enable quotas on. For example: - - -/dev/da1s2g /home ufs rw,userquota 1 2 - - Similarly, to enable group quotas, use the - groupquota option instead of the - userquota keyword. To enable both user and group - quotas, change the entry as follows: - - -/dev/da1s2g /home ufs rw,userquota,groupquota 1 2 - - By default the quota files are stored in the root directory of the - file system with the names quota.user and - quota.group for user and group quotas respectively. - See man fstab 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. - - At this point you should reboot your system with your new kernel. - /etc/rc will automatically run the appropriate - commands to create the initial quota files for all of the quotas you - enabled in /etc/fstab, so there is no need to - manually create any zero length quota files. - - In the normal course of operations you should not be required to run - the quotacheck, quotaon, or - quotaoff commands manually. However, you may want to - read their man pages just to be familiar with their operation. - - - - Setting Quota Limits - - Once you have configured your system to enable quotas, verify that - they really are enabled. An easy way to do this is to run - - &prompt.root; quota -v - - You should see a one line summary of disk usage and current quota - limits for each file system that quotas are enabled on. - - You are now ready to start assigning quota limits with the - edquota command. - - 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. - - 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. - - 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. - - The following is an example of what you might see when you run - then edquota command. When the - edquota command is invoked, you are placed into the - editor specified by the EDITOR environment variable, or - in the vi editor if the EDITOR - variable is not set, to allow you to edit the quota limits. - - &prompt.root; edquota -u test - - -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) - - 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: - /usr: blocks in use: 65, limits (soft = 50, hard = - 75) to: /usr: blocks in use: 65, - limits (soft = 500, hard = 600) - - The new quota limits will be in place when you exit the - editor. - - Sometimes it is desirable to set quota limits on a range of uids. - This can be done by use of the option on the - edquota command. First, assign the desired quota - limit to a user, and then run edquota -p protouser - startuid-enduid. For example, if user - test has the desired quota limits, the following - command can be used to duplicate those quota limits for uids 10,000 - through 19,999: - - &prompt.root; edquota -p test 10000-19999 - - 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. - - See man edquota for more detailed - information. - - - - Checking Quota Limits and Disk Usage - - You can use either the quota or the - repquota commands to check quota limits and disk - usage. The quota 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 repquota command can be - used to get a summary of all quotas and disk usage for file systems with - quotas enabled. - - The following is some sample output from the quota - -v command for a user that has quota limits on two file - systems. - - - -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 - - On the /usr 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 - * which indicates that the user is currently over - their quota limit. - - Normally file systems that the user is not using any disk space on - will not show up in the output from the quota - command, even if they have a quota limit assigned for that file system. - The option will display those file systems, such as - the /usr/var file system in the above - example. - - - - * Quotas over NFS - - This section is still under development. - - - - - 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 @@ - - - - Security - - - DES, MD5, and Crypt - - Contributed by &a.wollman; 24 September - 1995. - - 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. - - 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 libcrypt - because the name of the C function to implement it is - crypt. 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. - - Meanwhile, work was also underway on the DES-based password hash - function. First, a version of the crypt 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 libcrypt contains only the code involved in - performing the one-way password hash, and a separate - libcipher 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. - - - Recognizing your <command>crypt</command> mechanism - - 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 - $1$. 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 $ character, so a relatively short - string which doesn't begin with a dollar sign is very likely a DES - password. - - Determining which library is being used on your system is fairly - easy for most programs, except for those like init - 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 - crypt are linked against - libcrypt, which for each type of library is a - symbolic link to the appropriate implementation. For example, on a - system using the DES versions: - - &prompt.user; ls -l /usr/lib/libcrypt* -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 - - On a system using the MD5-based libraries, the same links will be - present, but the target will be libscrypt rather - than libdescrypt. - - - - - - - S/Key - - Contributed by &a.wollman; 25 September - 1995. - - 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. - - 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 - key program and accepted by the - keyinit 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 key program - (and sometimes the keyinit program) which it uses to - generate one-time passwords; we will call it a “secret - password” or just unqualified “password”. - - 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. - - 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 login and su 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.) - - There are four programs involved in the S/Key system which we will - discuss below. The key program accepts an iteration - count, a seed, and a secret password, and generates a one-time password. - The keyinit 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 keyinfo program examines the - /etc/skeykeys file and prints out the invoking - user's current iteration count and seed. Finally, the - login and su programs contain the - necessary logic to accept S/Key one-time passwords for authentication. - The login program is also capable of disallowing the - use of UNIX passwords on connections coming from specified - addresses. - - There are four different sorts of operations we will cover. The - first is using the keyinit 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 - keyinit program over an insecure connection, in - conjunction with the key program over a secure - connection, to do the same. The third is using the - key program to log in over an insecure connection. - The fourth is using the key 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). - - - Secure connection initialization - - 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 keyinit command without any - parameters while logged in as yourself: - - &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. -Enter secret password: ) I typed my pass phrase here -Again secret password: ) I typed it again ID - -wollman s/key is 99 ha73896 ) discussed below SAG -HAS FONT GOUT FATE BOOM ) - - There is a lot of information here. At theEnter secret - password: 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. - - - - Insecure connection initialization - - 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 key 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 keyinit -s command: - - &prompt.user; keyinit -s -Updating wollman: Old key: kh94741 -Reminder you need the 6 English words from the skey command. -Enter sequence count from 1 to 9999: 100 ) I typed this -Enter new key [default kh94742]: -s/key 100 kh94742 - - To accept the default seed (which the keyinit - program confusingly calls a key), press return. - Then move over to your secure connection or S/Key desk accessory, and - give it the same parameters: - - &prompt.user; key 100 kh94742 -Reminder - Do not use this program while logged in via telnet or rlogin. -Enter secret password: ) I typed my secret password -HULL NAY YANG TREE TOUT VETO - - Now switch back over to the insecure connection, and copy the - one-time password generated by key over to the - keyinit program: - - s/key access password: HULL NAY YANG TREE TOUT VETO -ID wollman s/key is 100 kh94742 -HULL NAY YANG TREE TOUT VETO - - The rest of the description from the previous section applies here - as well. - - - - Diversion: a login prompt - - Before explaining how to generate one-time passwords, we should go - over an S/Key login prompt: - - &prompt.user; telnet himalia -Trying 18.26.0.186... -Connected to himalia.lcs.mit.edu. -Escape character is '^]'. -s/key 92 hi52030 -Password: - - 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. - - If this machine were configured to disallow UNIX passwords over a - connection from my machine, the prompt would have also included the - annotation (s/key required), indicating that only - S/Key one-time passwords will be accepted. - - - - Generating a single one-time password - - Now, to generate the one-time password needed to answer this login - prompt, we use a trusted machine and the key - program. (There are versions of the key program - from DOS and Windows machines, and there is an S/Key desk accessory - for Macintosh computers as well.) The command-line - key program takes as its parameters the iteration - count and seed; you can cut-and-paste right from the login prompt - starting at key to the end of the line. - Thus: - - &prompt.user; key 92 hi52030 ) pasted from previous section -Reminder - Do not use this program while logged in via telnet or rlogin. -Enter secret password: ) I typed my secret password -ADEN BED WOLF HAW HOT STUN - - And in the other window: - - s/key 92 hi52030 ) from previous section -Password: - (turning echo on) -Password:ADEN BED WOLF HAW HOT STUN -Last login: Wed Jun 28 15:31:00 from halloran-eldar.l -[etc.] - - This is the easiest mechanism if you have a - trusted machine. There is a Java S/Key key applet, - The Java OTP - Calculator, that you can download and run locally on any - Java supporting browser. - - - - Generating multiple one-time passwords - - Sometimes we have to go places where no trusted machines or - connections are available. In this case, it is possible to use the - key command to generate a number of one-time - passwords in the same command; these can then be printed out. For - example: - - &prompt.user; key -n 25 57 zz99999 -Reminder - Do not use this program while logged in via telnet or rlogin. -Enter secret password: -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 - - The requests twenty-five keys in sequence; - the indicates the ending - iteration number; and the rest is as before. Note that these are - printed out in reverse 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 lpr. - 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. - - - - Restricting use of UNIX passwords - - The configuration file /etc/skey.access 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. - - If there is no /etc/skey.access 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 - skey.access file. In all cases, UNIX passwords - are permitted on the console. - - Here is a sample configuration file which illustrates the three - most common sorts of configuration statements: - - -permit internet 18.26.0.0 255.255.0.0 -permit user jrl -permit port ttyd0 - - The first line (permit internet) 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. - - The second line (permit user) 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 - key program, like those with dumb terminals, or - those who are uneducable. - - The third line (permit port) allows all users - logging in on the specified terminal line to use UNIX passwords; this - would be used for dial-ups. - - - - - Kerberos - - Contributed by &a.markm; (based on contribution by - &a.md;). - - 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. - - 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. - - 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. - - For those needing to get a legal foreign distribution of this - software, please do not get it from a USA or Canada - site. You will get that site in big trouble! A - legal copy of this is available from ftp.internat.FreeBSD.org, which is in South - Africa and an official FreeBSD mirror site. - - - Creating the initial database - - 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 /etc/kerberosIV and check that - only the following files are present: - - &prompt.root; cd /etc/kerberosIV -&prompt.root; ls -README krb.conf krb.realms - - If any additional files (such as principal.* - or master_key) exist, then use the - kdb_destroy command to destroy the old Kerberos - database, of if Kerberos is not running, simply delete the extra - files. - - You should now edit the krb.conf and - krb.realms files to define your Kerberos realm. - In this case the realm will be GRONDAR.ZA and the - server is grunt.grondar.za. We edit or create - the krb.conf file: - - &prompt.root; cat krb.conf -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 - - 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. - - 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 admin - server 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. - - Now we have to add grunt.grondar.za - to the GRONDAR.ZA realm and also add an entry to - put all hosts in the .grondar.za - domain in the GRONDAR.ZA realm. The - krb.realms file would be updated as - follows: - - &prompt.root; cat krb.realms -grunt.grondar.za GRONDAR.ZA -.grondar.za GRONDAR.ZA -.berkeley.edu CS.BERKELEY.EDU -.MIT.EDU ATHENA.MIT.EDU -.mit.edu ATHENA.MIT.EDU - - 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. - - The first line puts the specific system into - the named realm. The rest of the lines show how to default systems of - a particular subdomain to a named realm. - - Now we are ready to create the database. This only needs to run - on the Kerberos server (or Key Distribution Centre). Issue the - kdb_init command to do this: - - &prompt.root; kdb_init -Realm name [default ATHENA.MIT.EDU ]: GRONDAR.ZA -You will be prompted for the database Master Password. -It is important that you NOT FORGET this password. - -Enter Kerberos master key: - - Now we have to save the key so that servers on the local machine - can pick it up. Use the kstash command to do - this. - - &prompt.root; kstash - -Enter Kerberos master key: - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! - - This saves the encrypted master password in - /etc/kerberosIV/master_key. - - - - Making it all run - - Two principals need to be added to the database for - each system that will be secured with Kerberos. - Their names are kpasswd and rcmd - These two principals are made for each system, with the instance being - the name of the individual system. - - These daemons, kpasswd and - rcmd allow other systems to change Kerberos - passwords and run commands like rcp, - rlogin and rsh. - - Now let's add these entries: - - &prompt.root; kdb_edit -Opening database... - -Enter Kerberos master key: - -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. - -Principal name: passwd -Instance: grunt - -<Not found>, Create [y] ? y - -Principal: passwd, Instance: grunt, kdc_key_ver: 1 -New Password: <---- enter RANDOM here -Verifying password - -New Password: <---- enter RANDOM here - -Random password [y] ? y - -Principal's new key version = 1 -Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? -Max ticket lifetime (*5 minutes) [ 255 ] ? -Attributes [ 0 ] ? -Edit O.K. -Principal name: rcmd -Instance: grunt - -<Not found>, Create [y] ? - -Principal: rcmd, Instance: grunt, kdc_key_ver: 1 -New Password: <---- enter RANDOM here -Verifying password - -New Password: <---- enter RANDOM here - -Random password [y] ? - -Principal's new key version = 1 -Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? -Max ticket lifetime (*5 minutes) [ 255 ] ? -Attributes [ 0 ] ? -Edit O.K. -Principal name: <---- null entry here will cause an exit - - - - Creating the server file - - We now have to extract all the instances which define the services - on each machine. For this we use the ext_srvtab - command. This will create a file which must be copied or moved - by secure means 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. - - - &prompt.root; ext_srvtab grunt -Enter Kerberos master key: - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Generating 'grunt-new-srvtab'.... - - Now, this command only generates a temporary file which must be - renamed to srvtab so that all the server can pick - it up. Use the mv command to move it into place on - the original system: - - &prompt.root; mv grunt-new-srvtab srvtab - - If the file is for a client system, and the network is not deemed - safe, then copy the - client-new-srvtab to - removable media and transport it by secure physical means. Be sure to - rename it to srvtab in the client's - /etc/kerberosIV directory, and make sure it is - mode 600: - - &prompt.root; mv grumble-new-srvtab srvtab -&prompt.root; chmod 600 srvtab - - - - Populating the database - - We now have to add some user entries into the database. First - let's create an entry for the user jane. Use the - kdb_edit command to do this: - - &prompt.root; kdb_edit -Opening database... - -Enter Kerberos master key: - -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. - -Principal name: jane -Instance: - -<Not found>, Create [y] ? y - -Principal: jane, Instance: , kdc_key_ver: 1 -New Password: <---- enter a secure password here -Verifying password - -New Password: <---- re-enter the password here -Principal's new key version = 1 -Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? -Max ticket lifetime (*5 minutes) [ 255 ] ? -Attributes [ 0 ] ? -Edit O.K. -Principal name: <---- null entry here will cause an exit - - - - Testing it all out - - First we have to start the Kerberos daemons. NOTE that if you - have correctly edited your /etc/rc.conf 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 /etc/kerberosIV - directory. - - &prompt.root; kerberos & -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; kadmind -n & -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! - - Now we can try using the kinit command to get a - ticket for the id jane that we created - above: - - &prompt.user; kinit jane -MIT Project Athena (grunt.grondar.za) -Kerberos Initialization for "jane" -Password: - - Try listing the tokens using klist to see if we - really have them: - - &prompt.user; klist -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 - - Now try changing the password using passwd to - check if the kpasswd daemon can get authorization to the Kerberos - database: - - &prompt.user; passwd -realm GRONDAR.ZA -Old password for jane: -New Password for jane: -Verifying password -New Password for jane: -Password changed. - - - - Adding <command>su</command> privileges - - Kerberos allows us to give each user who - needs root privileges their own separate - supassword. We could now add an id which is - authorized to su to root. - This is controlled by having an instance of root - associated with a principal. Using kdb_edit we can - create the entry jane.root in the Kerberos - database: - - &prompt.root; kdb_edit -Opening database... - -Enter Kerberos master key: - -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. - -Principal name: jane -Instance: root - -<Not found>, Create [y] ? y - -Principal: jane, Instance: root, kdc_key_ver: 1 -New Password: <---- enter a SECURE password here -Verifying password - -New Password: <---- re-enter the password here - -Principal's new key version = 1 -Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? -Max ticket lifetime (*5 minutes) [ 255 ] ? 12 <--- Keep this short! -Attributes [ 0 ] ? -Edit O.K. -Principal name: <---- null entry here will cause an exit - - Now try getting tokens for it to make sure it works: - - &prompt.root; kinit jane.root -MIT Project Athena (grunt.grondar.za) -Kerberos Initialization for "jane.root" -Password: - - Now we need to add the user to root's .klogin - file: - - &prompt.root; cat /root/.klogin -jane.root@GRONDAR.ZA - - Now try doing the su: - - &prompt.user; su -Password: - - and take a look at what tokens we have: - - &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 - - - - Using other commands - - In an earlier example, we created a principal called - jane with an instance root. - This was based on a user with the same name as the principal, and this - is a Kerberos default; that a - <principal>.<instance> of the form - <username>.root will allow - that <username> to su to - root if the necessary entries are in the .klogin - file in root's home directory: - - &prompt.root; cat /root/.klogin -jane.root@GRONDAR.ZA - - Likewise, if a user has in their own home directory lines of the - form: - - &prompt.user; cat ~/.klogin -jane@GRONDAR.ZA -jack@GRONDAR.ZA - - This allows anyone in the GRONDAR.ZA realm - who has authenticated themselves to jane or - jack (via kinit, see above) - access to rlogin to jane's - account or files on this system (grunt) via - rlogin, rsh or - rcp. - - For example, Jane now logs into another system, using - Kerberos: - - &prompt.user; kinit -MIT Project Athena (grunt.grondar.za) -Password: -%prompt.user; rlogin grunt -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 - - Or Jack logs into Jane's account on the same machine (Jane having - set up the .klogin file as above, and the person - in charge of Kerberos having set up principal - jack with a null instance: - - &prompt.user; kinit -&prompt.user; rlogin grunt -l jane -MIT Project Athena (grunt.grondar.za) -Password: -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 - - - - - Firewalls - - Contributed by &a.gpalmer; and &a.alex;. - - 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. - - - People often think that having a firewall between your companies - internal network and the “Big Bad Internet” will solve all - your security problems. - - 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. - - - - What is a firewall? - - There are currently two distinct types of firewalls in common use - on the Internet today. The first type is more properly called a - packet filtering router, 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 proxy - servers, rely on daemons to provide authentication and to - forward packets, possibly on a multi-homed machine which has kernel - packet forwarding disabled. - - Sometimes sites combine the two types of firewalls, so that only a - certain machine (known as a bastion host) 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. - - FreeBSD comes with a kernel packet filter (known as - IPFW), 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. - - - Packet filtering routers - - 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. - - 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”. - - 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). - - - - Proxy servers - - Proxy servers are machines which have had the normal system - daemons (telnetd, ftpd, etc) replaced with special servers. These - servers are called proxy servers 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). - - 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. - - 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. - - - - - What does IPFW allow me to do? - - IPFW, 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. - - There are two related parts to IPFW. - 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. - - As a result of the way that IPFW is - designed, you can use IPFW on non-router - machines to perform packet filtering on incoming and outgoing - connections. This is a special case of the more general use of - IPFW, and the same commands and techniques - should be used in this situation. - - - - Enabling IPFW on FreeBSD - - As the main part of the IPFW 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 reconfiguring - the kernel for more details on how to recompile your - kernel. - - There are currently three kernel configuration options relevant to - IPFW: - - - - options IPFIREWALL - - - Compiles into the kernel the code for packet - filtering. - - - - - options IPFIREWALL_VERBOSE - - - 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. - - - - - options IPFIREWALL_VERBOSE_LIMIT=10 - - - 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. - - 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: - - &prompt.root; ipfw zero 4500 - Where 4500 is the chain entry you wish to continue - logging. - - - - - Previous versions of FreeBSD contained an - IPFIREWALL_ACCT option. This is now obsolete as - the firewall code automatically includes accounting - facilities. - - - - Configuring IPFW - - The configuration of the IPFW 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. - - 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. - - - Altering the IPFW rules - - The syntax for this form of the command is: - - ipfw - -N - command - index - action - log - protocol - addresses - options - - - There is one valid flag when using this form of the - command: - - - - -N - - - Resolve addresses and service names in output. - - - - - The command given can be shortened to the - shortest unique form. The valid commands - are: - - - - add - - - Add an entry to the firewall/accounting rule list - - - - - delete - - - Delete an entry from the firewall/accounting rule - list - - - - - Previous versions of IPFW used - separate firewall and accounting entries. The present version - provides packet accounting with each firewall entry. - - If an index 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). - - The log option causes matching rules to be - output to the system console if the kernel was compiled with - IPFIREWALL_VERBOSE. - - Valid actions are: - - - - reject - - - Drop the packet, and send an ICMP host or port unreachable - (as appropriate) packet to the source. - - - - - allow - - - Pass the packet on as normal. (aliases: - pass and - accept) - - - - - deny - - - Drop the packet. The source is not notified via an - ICMP message (thus it appears that the packet never - arrived at the destination). - - - - - count - - - Update packet counters but do not allow/deny the packet - based on this rule. The search continues with the next chain - entry. - - - - - Each action will be recognized by the - shortest unambiguous prefix. - - The protocols which can be specified - are: - - - - all - - - Matches any IP packet - - - - - icmp - - - Matches ICMP packets - - - - - tcp - - - Matches TCP packets - - - - - udp - - - Matches UDP packets - - - - - The address specification is: - - - from - address/maskport - to - address/markport - via interface - - - You can only specify port in - conjunction with protocols which support ports - (UDP and TCP). - - The is optional and may specify the IP - address or domain name of a local IP interface, or an interface name - (e.g. ed0) to match only packets coming - through this interface. Interface unit numbers can be specified - with an optional wildcard. For example, ppp* - would match all kernel PPP interfaces. - - The syntax used to specify an - address/mask is: - - address - - or - - address/mask-bits - - or - - address:mask-pattern - - - A valid hostname may be specified in place of the IP address. - is a decimal - number representing how many bits in the address mask should be set. - e.g. specifying 192.216.222.1/24 will create a - mask which will allow any address in a class C subnet (in this case, - 192.216.222) to be matched. - is an IP - address which will be logically AND'ed with the address given. The - keyword any may be used to specify “any IP - address”. - - The port numbers to be blocked are specified as: - - - port,port,port… - - - to specify either a single port or a list of ports, or - - - port-port - - - to specify a range of ports. You may also combine a single range - with a list, but the range must always be specified first. - - The options available are: - - - - frag - - - Matches if the packet is not the first fragment of the - datagram. - - - - - in - - - Matches if the packet is on the way in. - - - - - out - - - Matches if the packet is on the way out. - - - - - ipoptions spec - - - Matches if the IP header contains the comma separated list - of options specified in spec. The - supported list of IP options are: ssrr - (strict source route), lsrr (loose source - route), rr (record packet route), and - ts (timestamp). The absence of a - particular option may be denoted with a leading - !. - - - - - established - - - 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 - established rules early in the - chain. - - - - - setup - - - Matches if the packet is an attempt to establish a TCP - connection (the SYN bit set is set but the ACK bit is - not). - - - - - tcpflags flags - - - Matches if the TCP header contains the comma separated - list of flags. The supported flags - are fin, syn, - rst, psh, - ack, and urg. The - absence of a particular flag may be indicated by a leading - !. - - - - - icmptypes types - - - Matches if the ICMP type is present in the list - types. The list may be specified - as any combination of ranges and/or individual types separated - by commas. Commonly used ICMP types are: 0 - echo reply (ping reply), 3 destination - unreachable, 5 redirect, - 8 echo request (ping request), and - 11 time exceeded (used to indicate TTL - expiration as with &man.traceroute.8;). - - - - - - - Listing the IPFW rules - - The syntax for this form of the command is: - - ipfw - -a - -t - -N - l - - - There are three valid flags when using this form of the - command: - - - - -a - - - While listing, show counter values. This option is the - only way to see accounting counters. - - - - - -t - - - 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. - - - - - -N - - - Attempt to resolve given addresses and service - names. - - - - - - - Flushing the IPFW rules - - The syntax for flushing the chain is: - - ipfw - flush - - - 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. - - - - Clearing the IPFW packet counters - - The syntax for clearing one or more packet counters is: - - ipfw - zero - index - - - When used without an index argument, - all packet counters are cleared. If an - index is supplied, the clearing operation - only affects a specific chain entry. - - - - - Example commands for ipfw - - This command will deny all packets from the host evil.crackers.org to the telnet port of the - host nice.people.org by being forwarded - by the router: - - &prompt.root ipfw add deny tcp from evil.crackers.org to nice.people.org 23 - - The next example denies and logs any TCP traffic from the entire - crackers.org network (a class C) to - the nice.people.org machine (any - port). - - &prompt.root; ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org - - 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: - - &prompt.root; ipfw add deny tcp from any to my.org/28 6000 setup - - To see the accounting records: - - &prompt.root; ipfw -a list - - or in the short form - - &prompt.root; ipfw -a l - - - You can also see the last time a chain entry was matched - with: - - &prompt.root; ipfw -at l - - - - Building a packet filtering firewall - - - 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. - - - 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. - - - If you use the logging versions of the accept - command, it can generate large 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 /var/log - is located on. - - - You should enable your firewall from - /etc/rc.conf.local or - /etc/rc.conf. The associated manpage explains - which knobs to fiddle and lists some preset firewall configurations. - If you do not use a preset configuration, ipfw list - will output the current ruleset into a file that you can - pass to rc.conf. If you do not use - /etc/rc.conf.local or - /etc/rc.conf to enable your firewall, - it is important to make sure your firewall is enabled before - any IP interfaces are configured. - - - The next problem is what your firewall should actually - do! 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: - - - - 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. - - - - Block all 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. - - - - 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 xhost - + 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. - - - - 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. - - - - Another checklist for firewall configuration is available from - CERT at ftp://ftp.cert.org/pub/tech_tips/packet_filtering - - As I said above, these are only guidelines. - 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. - - - - - - 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 @@ - - - - Serial Communications - - - Serial Basics - - Assembled from FAQ. - - 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. - - The ttydX (or - cuaaX) 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 - - &prompt.root; stty -a -f /dev/ttyd1 - - 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 CLOCAL mode, 8 bits, and - XON/XOFF flow control by default for ttyd5, - do: - - &prompt.root; stty -f /dev/ttyid5 clocal cs8 ixon ixoff - - A good place to do this is in /etc/rc.serial. - Now, an application will have these settings by default when it opens - ttyd5. It can still change these settings to its - liking, though. - - 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 ttyd5 to - 57600 bps, do - - &prompt.root; stty -f /dev/ttyld5 57600 - - Now, an application that opens ttyd5 and tries - to change the speed of the port will be stuck with 57600 bps. - - Naturally, you should make the initial state and lock state devices - writable only by root. The - MAKEDEV script does not do - this when it creates the device entries. - - - - Terminals - - Contributed by &a.kelly; 28 July 1996 - - 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. - - - Uses and Types of Terminals - - The original Unix systems did not have consoles. Instead, people - logged in and ran programs through terminals that were connected to - the computer's serial ports. It is quite similar to using a modem and - some terminal software to dial into a remote system to do text-only - work. - - Today's PCs have consoles capable of high quality graphics, but - the ability to establish a login session on a serial port still exists - in nearly every Unix-style operating system today; FreeBSD is no - exception. By using a terminal attached to a unused serial port, you - can log in and run any text program that you would normally run on the - console or in an xterm window in the X Window - System. - - For the business user, you can attach many terminals to a FreeBSD - system and place them on your employees' desktops. For a home user, a - spare computer such as an older IBM PC or a Macintosh can be a - terminal wired into a more powerful computer running FreeBSD. You can - turn what might otherwise be a single-user computer into a powerful - multiple user system. - - For FreeBSD, there are three kinds of terminals: - - - - Dumb terminals - - - - PCs acting as terminals - - - - X terminals - - - - The remaining subsections describe each kind. - - - Dumb Terminals - - Dumb terminals are specialized pieces of hardware that let you - connect to computers over serial lines. They are called - “dumb” because they have only enough computational power - to display, send, and receive text. You cannot run any programs on - them. It is the computer to which you connect them that has all the - power to run text editors, compilers, email, games, and so - forth. - - There are hundreds of kinds of dumb terminals made by many - manufacturers, including Digital Equipment Corporation's VT-100 and - Wyse's WY-75. Just about any kind will work with FreeBSD. Some - high-end terminals can even display graphics, but only certain - software packages can take advantage of these advanced - features. - - Dumb terminals are popular in work environments where workers do - not need access to graphic applications such as those provided by - the X Window System. - - - - PCs Acting As Terminals - - If a dumb terminal 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 terminal emulation - software to run on the computer. - - Such a configuration is popular in homes. For example, if your - spouse is busy working on your FreeBSD system's console, you can do - some text-only work at the same time from a less powerful personal - computer hooked up as a terminal to the FreeBSD system. - - - - X Terminals - - X terminals are the most sophisticated kind of terminal - available. Instead of connecting to a serial port, they usually - connect to a network like Ethernet. Instead of being relegated to - text-only applications, they can display any X application. - - We introduce X terminals just for the sake of completeness. - However, this chapter does not cover setup, - configuration, or use of X terminals. - - - - - Cables and Ports - - 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 Configuration. - - - Cables - - Because terminals use serial ports, you need to use - serial—also known as RS-232C—cables to connect the - terminal to the FreeBSD system. - - There are a couple of kinds of serial cables. Which one - you'll use depends on the terminal you want to connect: - - - - If you are connecting a personal computer to act as a - terminal, use a null-modem - cable. A null-modem cable connects two computers or terminals - together. - - - - 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 null-modem cable. - If that does not work, then try a standard cable. - - - - Also, the serial port on both the terminal - and your FreeBSD system must have connectors that will fit the cable - you are using. - - - Null-modem cables - - A null-modem cable passes some signals straight through, like - “signal ground,” but switches other signals. For - example, the “send data” pin on one end goes to the - “receive data” pin on the other end. - - If you like making your own cables, here is a table showing a - recommended way to construct a null-modem cable for use with - terminals. This table shows the RS-232C signal names and the pin - numbers on a DB-25 connector. - - - - - - Signal - Pin # - - Pin # - Signal - - - - - - TxD - 2 - connects to - 3 - RxD - - - - RxD - 3 - connects to - 2 - TxD - - - - DTR - 20 - connects to - 6 - DSR - - - - DSR - 6 - connects to - 20 - DTR - - - - SG - 7 - connects to - 7 - SG - - - - DCD - 8 - connects to - 4 - RTS - - - - RTS - 4 - - 5 - CTS - - - - CTS - 5 - connects to - 8 - DCD - - - - - - - For DCD to RTS, connect pins 4 to 5 internally in the - connector hood, and then to pin 8 in the remote - hood. - - - - - Standard RS-232C Cables - - 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. - - - - - Ports - - 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. - - - Kinds of Ports - - Several kinds of serial ports exist. Before you purchase or - construct a cable, you need to make sure it will fit the ports on - your terminal and on the FreeBSD system. - - Most terminals will have DB25 ports. Personal computers, - including PCs running FreeBSD, will have DB25 or DB9 ports. If you - have a multiport serial card for your PC, you may have RJ-12 or - RJ-45 ports. - - See the documentation that accompanied the hardware for - specifications on the kind of port in use. A visual inspection of - the port often works, too. - - - - Port Names - - In FreeBSD, you access each serial port through an entry in - the /dev directory. There are two different - kinds of entries: - - - - Callin ports are named - /dev/ttydX - where X is the port number, - starting from zero. Generally, you use the callin port for - terminals. Callin ports require that the serial line assert - the data carrier detect (DCD) signal to work. - - - - Callout ports are named - /dev/cuaaX. - 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. - - - - See the &man.sio.4; manual page for more information. - - If you have connected a terminal to the first serial port - (COM1 in DOS parlance), then you want to - use /dev/ttyd0 to refer to the terminal. If - it is on the second serial port (also known as - COM2), it is - /dev/ttyd1, and so forth. - - Note that you may have to configure your kernel to support - each serial port, especially if you have a multiport serial card. - See Configuring the FreeBSD - Kernel for more information. - - - - - - Configuration - - This section describes what you need to configure on your FreeBSD - system to enable a login session on a terminal. It assumes you have - already configured your kernel to support the serial port to which the - terminal is connected—and that you have connected it. - - In a nutshell, you need to tell the init - process, which is responsible for process control and initialization, - to start a getty process, which is responsible for - reading a login name and starting the login - program. - - To do so, you have to edit the /etc/ttys - file. First, use the su command to become root. - Then, make the following changes to - /etc/ttys: - - - - Add an line to /etc/ttys for the entry in - the /dev directory for the serial port if it - is not already there. - - - - Specify that /usr/libexec/getty be run on - the port, and specify the appropriate - getty type from the - /etc/gettytab file. - - - - Specify the default terminal type. - - - - Set the port to “on.” - - - - Specify whether the port should be - “secure.” - - - - Force init to reread the - /etc/ttys file. - - - - As an optional step, you may wish to create a custom - getty type for use in step 2 by making an - entry in /etc/gettytab. 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. - - The remaining sections detail how to do these steps. We will use - a running example throughout these sections to illustrate what we need - to do. In our example, we will connect two terminals to the system: a - Wyse-50 and a old 286 IBM PC running Procomm terminal software - emulating a VT-100 terminal. We connect the Wyse to the second serial - port and the 286 to the sixth serial port (a port on a multiport - serial card). - - For more information on the /etc/ttys - file, see the &man.ttys.5; manual page. - - - Adding an Entry to <filename>/etc/ttys</filename> - - First, you need to add an entry to the - /etc/ttys file, unless one is already - there. - - The /etc/ttys file lists all of the ports - on your FreeBSD system where you want to allow logins. For example, - the first virtual console ttyv0 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 /dev entry without the - /dev part. - - When you installed your FreeBSD system, the - /etc/ttys file included entries for the first - four serial ports: ttyd0 through - ttyd3. If you are attaching a terminal on one - of those ports, you do not need to add an entry. - - In our example, we attached a Wyse-50 to the second serial port, - ttyd1, which is already in the file. We need - to add an entry for the 286 PC connected to the sixth serial port. - Here is an excerpt of the /etc/ttys file after - we add the new entry: - - -ttyd1 "/usr/libexec/getty std.9600" unknown off secure -ttyd5 - - - - Specifying the <replaceable>getty</replaceable> Type - - 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 /usr/libexec/getty. It is what provides the - login: prompt. - - The program getty takes one (optional) - parameter on its command line, the getty - type. A getty type tells about - characteristics on the terminal line, like bps rate and parity. The - getty program reads these characteristics from - the file /etc/gettytab. - - The file /etc/gettytab contains lots of - entries for terminal lines both old and new. In almost all cases, - the entries that start with the text std will - work for hardwired terminals. These entries ignore parity. There is - a std 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. - - When setting the getty type in the - /etc/ttys file, make sure that the - communications settings on the terminal match. - - For our example, the Wyse-50 uses no parity and connects at - 38400 bps. The 286 PC uses no parity and connects at 19200 bps. - Here is the /etc/ttys file so far (showing just - the two terminals in which we are interested): - - -ttyd1 "/usr/libexec/getty std.38400" unknown off secure -ttyd5 "/usr/libexec/getty std.19200" - - Note that the second field—where we specify what program - to run—appears in quotes. This is important, otherwise the - type argument to getty might be interpreted as - the next field. - - - - Specifying the Default Terminal Type - - The third field in the /etc/ttys file lists - the default terminal type for the port. For dialup ports, you - typically put unknown or - dialup in this field because users may dial up - with practically any kind of terminal or software. For hardwired - terminals, the terminal type does not change, so you can put a real - terminal type in this field. - - Users will usually use the tset program in - their .login or .profile - files to check the terminal type and prompt for one if necessary. - By setting a terminal type in the /etc/ttys - file, users can forego such prompting. - - To find out what terminal types FreeBSD supports, see the - file /usr/share/misc/termcap. It lists - about 600 terminal types. You can add more if you wish. See - the &man.termcap.5; manual page for information. - - In our example, the Wyse-50 is a Wyse-50 type of terminal - (although it can emulate others, we will leave it in Wyse-50 mode). - The 286 PC is running Procomm which will be set to emulate a VT-100. - Here are the pertinent yet unfinished entries from the - /etc/ttys file: - - -ttyd1 "/usr/libexec/getty std.38400" wy50 off secure -ttyd5 "/usr/libexec/getty std.19200" vt100 - - - - Enabling the Port - - The next field in /etc/ttys, the fourth - field, tells whether to enable the port. Putting - on here will have the init - process start the program in the second field, - getty, which will prompt for a login. If you put - off in the fourth field, there will be no - getty, and hence no logins on the port. - - So, naturally, you want an on in this field. - Here again is the /etc/ttys file. We have - turned each port on. - - -ttyd1 "/usr/libexec/getty std.38400" wy50 on secure -ttyd5 "/usr/libexec/getty std.19200" vt100 on - - - - Specifying Secure Ports - - We have arrived at the last field (well, almost: there is an - optional window specifier, but we will ignore - that). The last field tells whether the port is secure. - - What does “secure” mean? - - It means that the root account (or any account with a user ID of - 0) may login on the port. Insecure ports do not allow root to - login. - - How do you use secure and insecure ports? - - By marking a port as insecure, the terminal to which it is - connected will not allow root to login. People who know the root - password to your FreeBSD system will first have to login using a - regular user account. To gain superuser privileges, they will then - have to use the su command. - - Because of this, you will have two records to help track down - possible compromises of root privileges: both the - login and the su command make - records in the system log (and logins are also recorded in the - wtmp file). - - By marking a port as secure, the terminal will allow root in. - People who know the root password will just login as root. You will - not have the potentially useful login and su - command records. - - Which should you use? - - Just use “insecure.” Use “insecure” - even for terminals not in - public user areas or behind locked doors. It is quite easy to login - and use su if you need superuser - privileges. - - Here finally are the completed entries in the - /etc/ttys file, with comments added to describe - where the terminals are: - - -ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure # Kitchen -ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure # Guest bathroom - - - - Force <command>init</command> to Reread - <filename>/etc/ttys</filename> - - When you boot FreeBSD, the first process, - init, will read the - /etc/ttys file and start the programs listed - for each enabled port to prompt for logins. - - After you edit /etc/ttys, you do not want - to have to reboot your system to get init to see - the changes. So, init will reread - /etc/ttys if it receives a SIGHUP (hangup) - signal. - - So, after you have saved your changes to - /etc/ttys, send SIGHUP to - init by typing: - - &prompt.root; kill -HUP 1 - - (The init process always - has process ID 1.) - - If everything is set up correctly, all cables are in place, and - the terminals are powered up, you should see login prompts. Your - terminals are ready for their first logins! - - - - - Debugging your connection - - 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. - - - - No login prompt appears - - - Make sure the terminal is plugged in and powered up. If it - is a personal computer acting as a terminal, make sure it is - running terminal emulation software on the correct serial - port. - - Make sure the cable is connected firmly to both the terminal - and the FreeBSD computer. Make sure it is the right kind of - cable. - - Make sure the terminal and FreeBSD agree on the bps rate and - parity settings. If you have a video display terminal, make - sure the contrast and brightness controls are turned up. If it - is a printing terminal, make sure paper and ink are in good - supply. - - Make sure that a getty process is running - and serving the terminal. Type &prompt.root; - ps -axww|grep getty to get a - list of running getty processes. You should - see an entry for the terminal. For example, the display - - 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1 - - shows that a getty is running on the second - serial port ttyd1 and is using the - std.38400 entry in - /etc/gettytab. - - If no getty process is running, make sure - you have enabled the port in /etc/ttys. - Make sure you have run kill -HUP 1. - - - - - Garbage appears instead of a login prompt - - - Make sure the terminal and FreeBSD agree on the bps rate and - parity settings. Check the getty processes to make sure the - correct getty type is in use. If - not, edit /etc/ttys and run kill - -HUP 1. - - - - - Characters appear doubled; the password appears when - typed - - - Switch the terminal (or the terminal emulation software) - from “half duplex” or “local echo” to - “full duplex.” - - - - - - - - Dialin Service - - Contributed by &a.ghelmer;. - - 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. - - - Prerequisites - - 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. - - - FreeBSD Version - - 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 (sio) 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. - - - - Terminology - - A quick rundown of terminology: - - - - bps - - - Bits per Second — the rate at which data is - transmitted - - - - - DTE - - - Data Terminal Equipment — for example, your - computer - - - - - DCE - - - Data Communications Equipment — your modem - - - - - RS-232 - - - EIA standard for serial communications via hardware - - - - - If you need more information about these terms and data - communications in general, the author remembers reading that - The RS-232 Bible (anybody have an ISBN?) is a - good reference. - - 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). - - - - External vs. Internal Modems - - 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. - - 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. - - - - Modems and Cables - - A background knowledge of these items is assumed - - - - 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) - - - - You are familiar with your modem's command set, or know - where to look up needed commands - - - - You know how to configure your modem (probably via a - terminal communications program) so you can set the non-volatile - RAM parameters - - - - 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: - - - - Transmitted Data (SD) - - - - Received Data (RD) - - - - Request to Send (RTS) - - - - Clear to Send (CTS) - - - - Data Set Ready (DSR) - - - - Data Terminal Ready (DTR) - - - - Carrier Detect (CD) - - - - Signal Ground (SG) - - - - FreeBSD needs the RTS and - CTS signals for flow-control at speeds above - 2400bps, the CD signal to detect when a call has - been answered or the line has been hung up, and the - DTR 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. - - 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. - - 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. - - - - Serial Interface Considerations - - 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. - - - - - Quick Overview - - Here is the process that FreeBSD follows to accept dialup logins. - A getty process, spawned by - init, patiently waits to open the assigned serial - port (/dev/ttyd0, for our example). The command - ps ax might show this: - - 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0 - - When a user dials the modem's line and the modems connect, the - CD line is asserted by the modem. The kernel - notices that carrier has been detected and completes - getty's open of the port. getty - sends a login: prompt at the specified initial line - speed. getty 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 getty's speed), getty tries - adjusting the line speeds until it receives reasonable - characters. - - We hope getty finds the correct speed and the - user sees a login: prompt. After the user enters - his/her login name, getty executes - /usr/bin/login, which completes the login by - asking for the user's password and then starting the user's - shell. - - Let's dive into the configuration... - - - - Kernel Configuration - - FreeBSD kernels typically come prepared to search for four serial - ports, known in the PC-DOS world as COM1:, - COM2:, COM3:, and - COM4:. 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. - - To see if your kernel recognizes any of your serial ports, watch - for messages while the kernel is booting, or use the - /sbin/dmesg command to replay the kernel's boot - messages. In particular, look for messages that start with the - characters sio. Hint: to view just the messages - that have the word sio, use the command: - - &prompt.root; /sbin/dmesg | grep 'sio' - - For example, on a system with four serial ports, these are the - serial-port specific kernel boot messages: - - 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 - - If your kernel does not recognize all of your serial ports, you - will probably need to configure a custom FreeBSD kernel for your - system. - - Please see the BSD System Manager's Manual chapter on - “Building Berkeley Kernels with Config” [the source for - which is in /usr/src/share/doc/smm] and - “FreeBSD Configuration Options” [in - /sys/conf/options and in - /sys/arch/conf/options.arch, - with arch for example being - i386] 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 - (srcdist/srcsys.?? in FreeBSD 1.1, - srcdist/sys.?? in FreeBSD 1.1.5.1, or the entire - source distribution in FreeBSD 2.0) to be able to configure and build - kernels. - - Create a kernel configuration file for your system (if you have - not already) by cding to - /sys/i386/conf. Then, if you are creating a new - custom configuration file, copy the file - GENERICAH (or GENERICBT, if - you have a BusTek SCSI controller on FreeBSD 1.x) to - YOURSYS, where YOURSYS is - the name of your system, but in upper-case letters. Edit the file, - and change the device lines: - - -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 - - 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. - - - port "IO_COM1" is a substitution for - port 0x3f8, IO_COM2 is - 0x2f8, IO_COM3 is - 0x3e8, and IO_COM4 is - 0x2e8, 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 - cannot 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). - - - When you are finished adjusting the kernel configuration file, use - the program config 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. - - - - Device Special Files - - Most devices in the kernel are accessed through “device - special files”, which are located in the - /dev directory. The sio - devices are accessed through the - /dev/ttyd? (dial-in) - and /dev/cua0? - (call-out) devices. On FreeBSD version 1.1.5 and higher, there are - also initialization devices - (/dev/ttyid? and - /dev/cuai0?) and - locking devices - (/dev/ttyld? and - /dev/cual0?). The - initialization devices are used to initialize communications port - parameters each time a port is opened, such as - crtscts for modems which use - CTS/RTS 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. - - - Making Device Special Files - - A shell script called MAKEDEV in the - /dev 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 COM ports, so - ignore it.) To use MAKEDEV to make dialup device - special files for COM1: (port 0), - cd to /dev and issue the - command MAKEDEV ttyd0. Likewise, to make dialup - device special files for COM2: (port 1), - use MAKEDEV ttyd1. - - MAKEDEV not only creates the - /dev/ttyd? device - special files, but also creates the - /dev/cua0? (and all - of the initializing and locking special files under FreeBSD 1.1.5 - and up) and removes the hardwired terminal special file - /dev/tty0?, if it - exists. - - After making new device special files, be sure to check the - permissions on the files (especially the - /dev/cua* 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 - /dev/cua* files should be sufficient: - - 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 - - These permissions allow the user uucp and - users in the group dialer to use the call-out - devices. - - - - - Configuration Files - - There are three system configuration files in the - /etc directory that you will probably need to - edit to allow dialup access to your FreeBSD system. The first, - /etc/gettytab, contains configuration information - for the /usr/libexec/getty daemon. Second, - /etc/ttys holds information that tells - /sbin/init what tty devices - should have getty processes running on them. - Lastly, you can place port initialization commands in the - /etc/rc.serial script if you have FreeBSD 1.1.5.1 - or higher; otherwise, you can initialize ports in the - /etc/rc.local script. - - 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. - - 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 - getty does not understand any particular modem's - connection speed reporting, getty gives a - login: 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 - <Enter> key until they see a recognizable - prompt. If the data rates do not match, getty sees - anything the user types as “junk”, tries going to the next - speed and gives the login: 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. - - The author will try to give balanced configuration information, - but is biased towards having the modem's data rate follow the - connection rate. - - - <filename>/etc/gettytab</filename> - - /etc/gettytab 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. - - - Locked-Speed Config - - If you are locking your modem's data communications rate at a - particular speed, you probably will not need to make any changes - to /etc/gettytab. - - - - Matching-Speed Config - - You will need to setup an entry in - /etc/gettytab to give - getty information about the speeds you wish to - use for your modem. If you have a 2400 bps modem, you can - probably use the existing D2400 entry. This - entry already exists in the FreeBSD 1.1.5.1 - gettytab file, so you do not need to add it - unless it is missing under your version of FreeBSD: - - -# -# 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: - - If you have a higher speed modem, you will probably need to - add an entry in /etc/gettytab; here is an - entry you could use for a 14.4 Kbps modem with a top interface - speed of 19.2 Kbps: - - -# -# 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: - - On FreeBSD 1.1.5 and later, this will result in 8-bit, no - parity connections. Under FreeBSD 1.1, add - :np: parameters to the - std.xxx entries at - the top of the file for 8 bits, no parity; otherwise, the default - is 7 bits, even parity. - - 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 - nx= (“next table”) capability. - Each of the lines uses a tc= (“table - continuation”) entry to pick up the rest of the - “standard” settings for a particular data rate. - - 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 gettytab entry starting a 57.6 Kbps: - - -# -# 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: - - 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. - - - - - <filename>/etc/ttys</filename> - - /etc/ttys is the list of - ttys for init to monitor. - /etc/ttys also provides security information to - login (user root may only - login on ttys marked secure). See the manual - page for - &man.ttys.5; for more information. - - You will need to either modify existing lines in - /etc/ttys or add new lines to make - init run getty 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: - - -ttyd0 "/usr/libexec/getty xxx" dialup on - - The first item in the above line is the device special file for - this entry — ttyd0 means - /dev/ttyd0 is the file that this - getty will be watching. The second item, - "/usr/libexec/getty - xxx" - (xxx will be replaced by the initial - gettytab capability) is the process - init will run on the device. The third item, - dialup, is the default terminal type. The fourth - parameter, on, indicates to - init that the line is operational. There can be - a fifth parameter, secure, but it should only be - used for terminals which are physically secure (such as the system - console). - - The default terminal type (dialup in the - example above) may depend on local preferences. - dialup is the traditional default terminal type - on dialup lines so that users may customize their login scripts to - notice when the terminal is dialup and - automatically adjust their terminal type. However, the author finds - it easier at his site to specify vt102 as the - default terminal type, since the users just use VT102 emulation on - their remote systems. - - After you have made changes to /etc/ttys, - you may send the init process a - HUP signal to re-read the file. You can use the - command &prompt.root; kill -1 - 1 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 - init. - - - Locked-Speed Config - - For a locked-speed configuration, your - ttys entry needs to have a fixed-speed entry - provided to getty. For a modem whose port - speed is locked at 19.2 Kbps, the ttys entry - might look like this: - - -ttyd0 "/usr/libexec/getty std.19200" dialup on - - If your modem is locked at a different data rate, substitute - the appropriate name for the - std.speed entry for - std.19200 from - /etc/gettytab for your modem's data - rate. - - - - Matching-Speed Config - - In a matching-speed configuration, your - ttys entry needs to reference the appropriate - beginning “auto-baud” (sic) entry in - /etc/gettytab. For example, if you added the - above suggested entry for a matching-speed modem that starts at - 19.2 Kbps (the gettytab entry containing the - V19200 starting point), your - ttys entry might look like this: - - -ttyd0 "/usr/libexec/getty V19200" dialup on - - - - - <filename>/etc/rc.serial</filename> or - <filename>/etc/rc.local</filename> - - High-speed modems, like V.32, V.32bis, and V.34 modems, need to - use hardware (RTS/CTS) flow control. You can - add stty commands to - /etc/rc.serial on FreeBSD 1.1.5.1 and up, or - /etc/rc.local on FreeBSD 1.1, to set the - hardware flow control flag in the FreeBSD kernel for the modem - ports. - - For example, on a sample FreeBSD 1.1.5.1 system, - /etc/rc.serial reads: - - -#!/bin/sh -# -# Serial port initial configuration - -stty -f /dev/ttyid1 crtscts -stty -f /dev/cuai01 crtscts - - This sets the termios flag - crtscts on serial port #1's - (COM2:) dialin and dialout initialization - devices. - - On an old FreeBSD 1.1 system, these entries were added to - /etc/rc.local to set the - crtscts flag on the devices: - - -# 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 - - 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. - - - - - Modem Settings - - 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 tip under FreeBSD) to set the - parameters. Connect to the modem using the same communications speed - as the initial speed getty will use and configure - the modem's non-volatile RAM to match these requirements: - - - - CD asserted when connected - - - - DTR asserted for operation; dropping DTR - hangs up line & resets modem - - - - CTS transmitted data flow control - - - - Disable XON/XOFF flow control - - - - RTS received data flow control - - - - Quiet mode (no result codes) - - - - No command echo - - - - Please read the documentation for your modem to find out what - commands and/or DIP switch settings you need to give it. - - For example, to set the above parameters on a USRobotics - Sportster 14,400 external modem, one could give these commands to - the modem: - - -ATZ -AT&C1&D2&H1&I0&R2&W - - 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. - - 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: - - - - Switch 1: UP — DTR Normal - - - - Switch 2: Do not care (Verbal Result Codes/Numeric Result - Codes) - - - - Switch 3: UP — Suppress Result Codes - - - - Switch 4: DOWN — No echo, offline commands - - - - Switch 5: UP — Auto Answer - - - - Switch 6: UP — Carrier Detect Normal - - - - Switch 7: UP — Load NVRAM Defaults - - - - Switch 8: Do not care (Smart Mode/Dumb Mode) - - - - Result codes should be disabled/suppressed for dialup modems to - avoid problems that can occur if getty mistakenly - gives a login: 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 getty and the modem. - - - Locked-speed Config - - 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: - - -ATZ -AT&B1&W - - - - Matching-speed Config - - 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: - - -ATZ -AT&B2&W - - - - Checking the Modem's Configuration - - 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 - ATI5 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 - ATZ and then ATI4. - - If you have a different brand of modem, check your modem's - manual to see how to double-check your modem's configuration - parameters. - - - - - Troubleshooting - - Here are a few steps you can follow to check out the dialup modem - on your system. - - - Checking out the FreeBSD system - - 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 DTR indicator lights when the - login: prompt appears on the system's console - — if it lights up, that should mean that FreeBSD has started a - getty process on the appropriate communications - port and is waiting for the modem to accept a call. - - If the DTR indicator doesn't light, login to - the FreeBSD system through the console and issue a ps - ax to see if FreeBSD is trying to run a - getty process on the correct port. You should see - a lines like this among the processes displayed: - - 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0 - 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1 - - If you see something different, like this: - - 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0 - - and the modem has not accepted a call yet, this means that - getty has completed its open on the - communications port. This could indicate a problem with the cabling - or a mis-configured modem, because getty should - not be able to open the communications port until - CD (carrier detect) has been asserted by the - modem. - - If you do not see any getty processes waiting - to open the desired - ttyd? port, - double-check your entries in /etc/ttys to see - if there are any mistakes there. Also, check the log file - /var/log/messages to see if there are any log - messages from init or getty - regarding any problems. If there are any messages, triple-check the - configuration files /etc/ttys and - /etc/gettytab, as well as the appropriate - device special files /dev/ttyd?, for any - mistakes, missing entries, or missing device special files. - - - - Try Dialing In - - 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 <Enter> - about once per second. If you still do not see a - login: prompt after a while, try sending a - BREAK. If you are using a high-speed modem to do - the dialing, try dialing again after locking the dialing modem's - interface speed (via AT&B1 on a USR - Sportster, for example). - - If you still cannot get a login: prompt, check - /etc/gettytab again and double-check - that - - - - The initial capability name specified in - /etc/ttys for the line matches a name of a - capability in /etc/gettytab - - - - Each nx= entry matches another - gettytab capability name - - - - Each tc= entry matches another - gettytab capability name - - - - 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 - DTR is asserted. If the modem seems to be - configured correctly, verify that the DTR line is - asserted by checking the modem's indicator lights (if it has - any). - - 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. - - - - - Acknowledgments - - Thanks to these people for comments and advice: - - - - &a.kelly; - - - for a number of good suggestions - - - - - - - - Dialout Service - - Information integrated from FAQ. - - 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. - - This is useful to log onto a BBS. - - 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. - - - Why cannot I run <command>tip</command> or - <command>cu</command>? - - On your system, the programs tip and - cu are probably executable only by - uucp and group dialer. You - can use the group dialer to control who has - access to your modem or remote systems. Just add yourself to group - dialer. - - Alternatively, you can let everyone on your system run - tip and cu by typing: - - &prompt.root; chmod 4511 /usr/bin/tip - - You do not have to run this command for cu, - since cu is just a hard link to - tip. - - - - My stock Hayes modem is not supported, what can I do? - - Actually, the man page for tip is out of date. - There is a generic Hayes dialer already built in. Just use - at=hayes in your /etc/remote - file. - - The Hayes driver is not smart enough to recognize some of the - advanced features of newer modems—messages like - BUSY, NO DIALTONE, or - CONNECT 115200 will just confuse it. You should - turn those messages off when you use tip (using - ATX0&W). - - Also, the dial timeout for tip is 60 seconds. - Your modem should use something less, or else tip will think there is - a communication problem. Try ATS7=45&W. - - Actually, as shipped tip does not yet support - it fully. The solution is to edit the file - tipconf.h in the directory - /usr/src/usr.bin/tip/tip Obviously you need the - source distribution to do this. - - Edit the line #define HAYES 0 to - #define HAYES 1. Then make and - make install. Everything works nicely after - that. - - - - How am I expected to enter these AT commands? - - Make what is called a “direct” entry in your - /etc/remote file. For example, if your modem is - hooked up to the first serial port, /dev/cuaa0, - then put in the following line: - - -cuaa0:dv=/dev/cuaa0:br#19200:pa=none - - Use the highest bps rate your modem supports in the br capability. - Then, type tip cuaa0 and you will be connected to - your modem. - - If there is no /dev/cuaa0 on your system, do - this: - - &prompt.root; cd /dev -&prompt.root; MAKEDEV cuaa0 - - Or use cu as root with the following command: - - &prompt.root; cu -lline -sspeed - - line is the serial port - (e.g./dev/cuaa0) and - speed is the speed - (e.g.57600). When you are done entering the AT - commands hit ~. to exit. - - - - The <literal>@</literal> sign for the pn capability does not - work! - - The @ sign in the phone number capability tells - tip to look in /etc/phones for a phone number. - But the @ sign is also a special character in - capability files like /etc/remote. Escape it - with a backslash: - - -pn=\@ - - - - How can I dial a phone number on the command line? - - Put what is called a “generic” entry in your - /etc/remote file. For example: - - -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: - - Then you can things like: - - &prompt.root; tip -115200 5551234 - - If you prefer cu over tip, - use a generic cu entry: - - -cu115200|Use cu to dial any number at 115200bps:\ - :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du: - - and type: - - &prompt.root; cu 5551234 -s 115200 - - - - Do I have to type in the bps rate every time I do that? - - Put in an entry for tip1200 or - cu1200, but go ahead and use whatever bps rate is - appropriate with the br capability. tip thinks a - good default is 1200 bps which is why it looks for a - tip1200 entry. You do not have to use 1200 bps, - though. - - - - I access a number of hosts through a terminal server. - - Rather than waiting until you are connected and typing - CONNECT <host> each time, use tip's - cm capability. For example, these entries in - /etc/remote: - - -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: - - will let you type tip pain or tip - muffin to connect to the hosts pain or muffin; and - tip deep13 to get to the terminal server. - - - - Can tip try more than one line for each site? - - This is often a problem where a university has several modem lines - and several thousand students trying to use them... - - Make an entry for your university in - /etc/remote and use @ for the - pn capability: - - -big-university:\ - :pn=\@:tc=dialout -dialout:\ - :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none: - - Then, list the phone numbers for the university in - /etc/phones: - - -big-university 5551111 -big-university 5551112 -big-university 5551113 -big-university 5551114 - - tip will try each one in the listed order, then - give up. If you want to keep retrying, run tip in - a while loop. - - - - Why do I have to hit CTRL+P twice to send CTRL+P once? - - CTRL+P is the default “force” character, used to tell - tip that the next character is literal data. You - can set the force character to any other character with the - ~s escape, which means “set a - variable.” - - Type - ~sforce=single-char - followed by a newline. single-char is any - single character. If you leave out - single-char, then the force character is - the nul character, which you can get by typing CTRL+2 or CTRL+SPACE. - A pretty good value for single-char is - SHIFT+CTRL+6, which I have seen only used on some terminal - servers. - - You can have the force character be whatever you want by - specifying the following in your $HOME/.tiprc - file: - - -force=<single-char> - - - - Suddenly everything I type is in UPPER CASE?? - - You must have pressed CTRL+A, tip's - “raise character,” specially designed for people with - broken caps-lock keys. Use ~s as above and set the - variable raisechar 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. - - Here is a sample .tiprc file perfect for Emacs users who need to - type CTRL+2 and CTRL+A a lot: - - -force=^^ -raisechar=^^ - - The ^^ is SHIFT+CTRL+6. - - - - How can I do file transfers with <command>tip</command>? - - If you are talking to another UNIX system, you can send and - receive files with ~p (put) and - ~t (take). These commands run - cat and echo on the remote - system to accept and send files. The syntax is: - - - ~p - local-file - remote-file - - - - ~t - remote-file - local-file - - - There is no error checking, so you probably should use another - protocol, like zmodem. - - - - How can I run zmodem with <command>tip</command>? - - To receive files, start the sending program on the remote end. - Then, type ~C rz to begin receiving them - locally. - - To send files, start the receiving program on the remote end. - Then, type ~C sz files - to send them to the remote system. - - - - - Setting Up the Serial Console - - &a.yokota; and &a.wpaul: - - The text is heavily based on - /sys/i386/boot/biosboot/README.serial written by - &a.wpaul;. - - - Introduction - - 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. - - 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 - (/boot/loader) as the third stage code. (See - &man.boot.8; and &man.loader.8; for more details on the boot - process.) - - In order to set up the serial console you must configure the boot - block code, the boot loader code and the kernel. - - 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. - - 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 /sys/i386/boot/biosboot/README.serial - instead. - - - - 6 Steps to Set up the Serial Console - - - - Prepare a serial cable. - - You will need either a null-modem cable or a standard serial - cable and a null-modem adapter. See for - a discussion on serial cables. - - - - Unplug your keyboard. - - 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. - - 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 Keyboard - failed then continues to boot normally.) - - 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. - - - Setting the keyboard to “Not installed” in the - BIOS setup does not 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. - - - - 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. - - - - - Plug a dumb terminal into COM1: - (sio0). - - 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 COM1: - (sio0), get one. At this time, there is - no way to select a port other than COM1: - for the boot blocks without recompiling the boot blocks. If you - are already using COM1: 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 COM1: will - be available on a file/compute/terminal server anyway; if you - really need COM1: for something else - (and you can not switch that something else to - COM2: (sio1)), - then you probably should not even be bothering with all this in - the first place.) - - - - Make sure the configuration file of your kernel has - appropriate flags set for COM1: - (sio0). - - Relevant flags are: - - - - 0x10 - - - 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 - described below, together with this flag. - - - - - 0x20 - - - Forces this unit to be the console (unless there is - another higher priority console), regardless of the - option discussed below. This flag - replaces the COMCONSOLE option in FreeBSD - versions 2.X. The flag 0x20 must be used - together with the flag. - - - - - 0x40 - - - Reserves this unit (in conjunction with - 0x10) 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 for more - information on remote debugging. - - - In FreeBSD 4.0-CURRENT or later the semantics of the - flag 0x40 are slightly different and - there is another flag to specify a serial port for remote - debugging. - - - - - - Example: - - -device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4 - - See &man.sio.4; for more details. - - If the flags were not set, you need to run UserConfig (on a - different console) or recompile the kernel. - - - - Create boot.config in the root directory - of the a partition on the boot drive. - - 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: - - - - - - - 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 - 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 - to tell the boot loader and the kernel - to use the video display as the console instead. - - - - - - - - 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 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. - 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 becomes the only console. - - - - - - - - Makes the boot block probe the keyboard. If no keyboard - is found, the and - options are automatically set. - - - Due to space constraints in the current version of the - boot blocks, the 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. Unfortunately there is no - workaround for this problem. - - - - - - Use either the option to select the - console automatically, or the option to - activate the serial console. - - You may include other options described in &man.boot.8; as - well. - - The options, except for , will be passed to - the boot loader (/boot/loader). 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 alone. This means that if you specify - the option but not the - option in /boot.config, 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. - - - - Boot the machine. - - When you start your FreeBSD box, the boot blocks will echo the - contents of /boot.config to the console. For - example; - - /boot.config: -P -Keyboard: no - - The second line appears only if you put in - /boot.config and indicates presence/absence - of the keyboard. These messages go to either serial or internal - console, or both, depending on the option in - /boot.config. - - - - - - Options - Message goes to - - - - - - none - internal console - - - - - serial console - - - - - serial and internal consoles - - - - - serial and internal consoles - - - - , keyboard present - internal console - - - - , keyboard absent - serial console - - - - - - 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. - - 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: - - >> FreeBSD/i386 BOOT -Default: 0:wd(0,a)/boot/loader -boot: - - Verify the above message appears on either the serial or - internal console or both, according to the options you put in - /boot.config. If the message appears in the - correct console, hit Enter/Return to continue the boot - process. - - 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 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. - - - - 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 . - - - - Summary - - Here is the summary of various settings discussed in this section - and the console eventually selected. - - - Case 1: You set the flags to 0x10 for sio0 - - device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4 - - - - - - Options in /boot.config - Console during boot blocks - Console during boot loader - Console in kernel - - - - - - nothing - internal - internal - internal - - - - - serial - serial - serial - - - - - serial and internal - internal - internal - - - - - serial and internal - serial - serial - - - - , keyboard present - internal - internal - internal - - - - , keyboard absent - serial and internal - serial - serial - - - - - - - - Case 2: You set the flags to 0x30 for sio0 - - device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4 - - - - - - Options in /boot.config - Console during boot blocks - Console during boot loader - Console in kernel - - - - - - nothing - internal - internal - serial - - - - - serial - serial - serial - - - - - serial and internal - internal - serial - - - - - serial and internal - serial - serial - - - - , keyboard present - internal - internal - serial - - - - , keyboard absent - serial and internal - serial - serial - - - - - - - - - Tips for the Serial Console - - - Setting A Faster Serial Port Speed - - 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 /etc/make.conf and compile new boot - blocks: - - BOOT_COMCONSOLE_SPEED=19200 - - If the serial console is configured in some other way than by - booting with , 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: - - options CONSPEED=19200 - - - - Using Serial Port Other Than <devicename>sio0</devicename> For - The Console - - Using a port other than sio0 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. - - - - Get the kernel source. - - - - Edit /etc/make.conf and set - BOOT_COMCONSOLE_PORT to the address of the - port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only - sio0 through - sio3 (COM1: - through COM4:) can be used; multiport - serial cards will not work. No interrupt setting is - needed. - - - - 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 sio1 - (COM2:) the console: - - device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3 - - or - - device sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3 - - The console flags for the other serial ports should not be - set. - - - - Recompile and install the boot blocks: - - &prompt.root; cd /sys/boot/i386/boot2 -&prompt.root; make -&prompt.root; make install - - - - Recompile and install the boot loader: - - &prompt.root; cd /sys/boot/i386/loader -&prompt.root; make -&prompt.root; make install - - - - Rebuild and install the kernel. - - - - Write the boot blocks to the boot disk with - &man.disklabel.8; and boot from the new kernel. - - - - - - Entering the DDB Debugger from the Serial Line - - 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: - - options BREAK_TO_DEBUGGER -options DDB - - - - Getting a Login Prompt on the Serial Console - - While this is not required, you may wish to get a - login 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. - - Open the file /etc/ttys with an editor - and locate the lines: - - 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 - - ttyd0 through ttyd3 - corresponds to COM1 through - COM4. Change off to - on for the desired port. If you have changed the - speed of the serial port, you need to change - std.9600 to match the current setting, e.g. - std.19200. - - You may also want to change the terminal type from - unknown to the actual type of your serial - terminal. - - After editing the file, you must kill -HUP 1 - to make this change take effect. - - - - - Changing Console from the Boot Loader - - 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. - - - Setting Up the Serial Console - - You can easily specify the boot loader and the kernel to use the - serial console by writing just one line in - /boot/loader.rc: - - set console=comconsole - - This will take effect regardless of the settings in the boot - block discussed in the previous section. - - You had better put the above line as the first line of - /boot/loader.rc so as to see boot messages on - the serial console as early as possible. - - Likewise, you can specify the internal console as: - - set console=vidconsole - - If you do not set the boot loader environment variable - console, the boot loader, and subsequently the - kernel, will use whichever console indicated by the - option in the boot block. - - In versions 3.2 or later, you may specify the console in - /boot/loader.conf.local or - /boot/loader.conf, rather than in - /boot/loader.rc. In this method your - /boot/loader.rc should look like: - - include /boot/loader.4th -start - - Then, create /boot/loader.conf.local and - put the following line there. - - console=comconsole - - or - - console=vidconsole - - See &man.loader.conf.5; for more information. - - - At the moment, the boot loader has no option equivalent to the - 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. - - - - - Using Serial Port Other than <devicename>sio0</devicename> for - the Console - - You need to recompile the boot loader to use a serial port other - than sio0 for the serial console. Follow the - procedure described in . - - - - - Caveats - - 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.' - - 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. - - - - - - 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 @@ - - - - - - FreeBSD Project Staff - - The FreeBSD Project is managed and operated by the following groups of - people: - - - The FreeBSD Core Team - - 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 specific - areas of the FreeBSD project landscape. - - (in alphabetical order by last name): - - - - &a.asami; - - - - &a.jmb; - - - - &a.ache; - - - - &a.bde; - - - - &a.gibbs; - - - - &a.dg; - - - - &a.jkh; - - - - &a.phk; - - - - &a.rich; - - - - &a.gpalmer; - - - - &a.jdp; - - - - &a.dfr; - - - - &a.sos; - - - - &a.peter; - - - - &a.wollman; - - - - &a.joerg; - - - - - - The FreeBSD Developers - - 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. - - - - &a.ugen; - - - - &a.dbaker; - - - - &a.mbarkah; - - - - &a.stb; - - - - &a.pb; - - - - &a.abial; - - - - &a.jb; - - - - &a.torstenb; - - - - &a.dburr; - - - - &a.charnier; - - - - &a.luoqi; - - - - &a.ejc; - - - - &a.kjc; - - - - &a.gclarkii; - - - - &a.archie; - - - - &a.chris; - - - - &a.alc; - - - - &a.cracauer; - - - - &a.adam; - - - - &a.dillon; - - - - &a.mdodd; - - - - &a.dufault; - - - - &a.uhclem; - - - - &a.tegge; - - - - &a.deischen; - - - - &a.eivind; - - - - &a.julian; - - - - &a.rse; - - - - &a.ru; - - - - &a.se; - - - - &a.jasone; - - - - &a.sef; - - - - &a.green; - - - - &a.fenner; - - - - &a.jfieber; - - - - &a.jfitz; - - - - &a.scrappy; - - - - &a.lars; - - - - &a.dirk; - - - - &a.shige; - - - - &a.billf; - - - - &a.gallatin; - - - - &a.tg; - - - - &a.brandon; - - - - &a.graichen; - - - - &a.cg; - - - - &a.jgreco; - - - - &a.rgrimes; - - - - &a.jmg; - - - - &a.hanai; - - - - &a.mharo; - - - - &a.thepish; - - - - &a.jhay; - - - - &a.sheldonh; - - - - &a.helbig; - - - - &a.ghelmer; - - - - &a.erich; - - - - &a.nhibma; - - - - &a.flathill; - - - - &a.hosokawa; - - - - &a.hsu; - - - - &a.foxfair; - - - - &a.tom; - - - - &a.mph; - - - - &a.shin; - - - - &a.itojun; - - - - &a.iwasaki; - - - - &a.mjacob; - - - - &a.gj; - - - - &a.nsj; - - - - &a.ljo; - - - - &a.kato; - - - - &a.andreas; - - - - &a.motoyuki; - - - - &a.jkoshy; - - - - &a.kuriyama; - - - - &a.grog; - - - - &a.jlemon; - - - - &a.truckman; - - - - &a.lile; - - - - &a.kevlo; - - - - &a.imp; - - - - &a.jmacd; - - - - &a.smace; - - - - &a.gehenna; - - - - &a.mckay; - - - - &a.mckusick; - - - - &a.ken; - - - - &a.hm; - - - - &a.tedm; - - - - &a.jim; - - - - &a.marcel; - - - - &a.amurai; - - - - &a.markm; - - - - &a.max; - - - - &a.newton; - - - - &a.rnordier; - - - - &a.davidn; - - - - &a.obrien; - - - - &a.danny; - - - - &a.ljo; - - - - &a.fsmp; - - - - &a.smpatel; - - - - &a.wpaul; - - - - &a.alfred; - - - - &a.wes; - - - - &a.cpiazza; - - - - &a.steve; - - - - &a.mpp; - - - - &a.jraynard; - - - - &a.darrenr; - - - - &a.csgr; - - - - &a.martin; - - - - &a.paul; - - - - &a.roberto; - - - - &a.chuckr; - - - - &a.guido; - - - - &a.dima; - - - - &a.sada; - - - - &a.nsayer; - - - - &a.wosch; - - - - &a.ats; - - - - &a.dick; - - - - &a.jseger; - - - - &a.simokawa; - - - - &a.vanilla; - - - - &a.msmith; - - - - &a.des; - - - - &a.brian; - - - - &a.mks; - - - - &a.stark; - - - - &a.karl; - - - - &a.sumikawa; - - - - &a.nyan; - - - - &a.tanimura; - - - - &a.taoka; - - - - &a.dt; - - - - &a.cwt; - - - - &a.pst; - - - - &a.hoek; - - - - &a.nectar; - - - - &a.swallace; - - - - &a.dwhite; - - - - &a.nate; - - - - &a.yokota; - - - - &a.jmz; - - - - - - The FreeBSD Documentation Project - - The FreeBSD - Documentation Project is responsible for a number of different - services, each service being run by an individual and his - deputies (if any): - - - - Documentation Project Manager - - - &a.nik; - - - - - Webmaster - - - &a.wosch; - - - - - Handbook & FAQ Editor - - - &a.faq; - - - - - News Editor - - - &a.nsj; - - Deputy: &a.john; - - - - - - In the Press Editor - - - &a.jkoshy - - - - - FreeBSD Really-Quick NewsLetter Editor - - - Chris Coleman chrisc@vmunix.com - - - - - Gallery Editor - - - &a.nsj; - - Deputy: &a.cawimm; - - - - - - Commercial Editor - - - &a.nik; - - - - - Web Changes Editor - - - - - - - - - User Groups Editor - - - - - - - - - LinuxDoc to DocBook conversion - - - &a.nik; - - - - - - - Who Is Responsible for What - - - - Principal Architect - - - &a.dg; - - - - - Documentation - Project Manager - - - &a.nik; - - - - - Internationalization - - - &a.ache; - - - - Networking - - - &a.wollman; - - - - - Postmaster - - - &a.jmb; - - - - - Release Coordinator - - - &a.jkh; - - - - - Public Relations & Corporate Liaison - - - &a.jkh; - - - - - Security - Officer - - - &a.imp; - - - - - Source - Repository Managers - - - Principal: &a.peter; - - Assistant: &a.jdp; - - International (Crypto): &a.markm; - - - - - Ports - Manager - - - &a.asami; - - - - - XFree86 Project, Inc. Liaison - - - &a.rich; - - - - - Usenet Support - - - &a.joerg; - - - - - GNATS - Administrator - - - &a.steve; - - - - - Webmaster - - - &a.wosch; - - - - - - - - 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 X Window System - - Pending the completion of this section, please refer to documentation - supplied by the The XFree86 Project, - Inc. - - - - 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 @@ - - - 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 @@ - - - - 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: - - - - 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. - - - - 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 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. - - - 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 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 @@ - - - - -
- -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 - - - -James -Raynard - -
-jraynard@freebsd.org -
- - - -August 17, 1997 - - -1997 -James Raynard - - -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 not 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 - - - - -Introduction<anchor id=foo> - -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 -sed and 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 POSIX and -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. - -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. - -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! - - - - -Introduction to Programming - -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 commands as they are usually -called. One way uses an interpreter, the other a -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. - - - - -Interpreters - -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. - -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. - -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 (sh, -csh) is itself an interpreter, and many people do in fact -write shell scripts to help with various -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. - - - - -Interpreters available with FreeBSD - -Here is a list of interpreters that are available as FreeBSD -packages, with a brief discussion of some of the more popular -interpreted languages. - -To get one of these packages, all you need to do is to click on -the hotlink for the package, then run -$ pkg_add package name - - -as root. Obviously, you will need to have a fully functional FreeBSD -2.1.0 or later system for the package to work! - - - -BASIC - -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, BASIC has been the first programming language -for many programmers. It's also the foundation for Visual -Basic. - -The Bywater -Basic Interpreter and the Phil -Cockroft's Basic Interpreter (formerly Rabbit Basic) are -available as FreeBSD FreeBSD -packages - - - -Lisp -A language that was developed in the late 1950s as an alternative to -the number-crunching 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 List Processing. Very popular in AI -(Artificial Intelligence) circles. - -Lisp is an extremely powerful and sophisticated language, but -can be rather large and unwieldy. - -FreeBSD has GNU -Common Lisp available as a package. - - - - -Perl -Very popular with system administrators for writing -scripts; also often used on World Wide Web servers for writing CGI -scripts. - -Version 4, which is probably still the most widely-used -version, comes with FreeBSD; the newer Perl -Version 5 is available as a package. - - - - -Scheme -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. - -FreeBSD has packages of the -Elk Scheme Interpreter, the -MIT Scheme Interpreter and the -SCM Scheme Interpreter. - - - - -Icon -The Icon Programming Language. - - - -Logo -Brian Harvey's LOGO Interpreter. - - - -Python -The Python Object-Oriented Programming Language - - - - - - - - - -Compilers - -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.If you run it in -the shell, you may get a core dump. - -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. - -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. - -As the edit-compile-run-debug cycle is rather tedious when -using separate programs, many commercial compiler makers have -produced Integrated Development Environments (IDEs -for short). FreeBSD does not have an IDE as such; however -it is possible to use Emacs for this purpose. This is discussed in -. - - - - - -Compiling with <command>cc</command> - -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 cc or 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. - -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. - - -Pre-process your source code to remove comments and do other -tricks like expanding macros in C. - - -Check the syntax of your code to see if you have obeyed the -rules of the language. If you have not, it will complain! - - -Convert the source code into assembly -language—this is very close to machine code, but still -understandable by humans. Allegedly.To be strictly -accurate, cc converts the source code into its own, -machine-independent p-code instead of assembly language -at this stage. - -Convert the assembly language into machine -code—yep, we are talking bits and bytes, ones and zeros -here. - -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. - -If you are trying to produce an executable from several -source code files, work out how to fit them all together. - -Work out how to produce something that the system's run-time -loader will be able to load into memory and run. - -Finally, write the executable on the file -system. - - - -The word compiling is often used to refer to just -steps 1 to 4—the others are referred to as -linking. Sometimes step 1 is referred to as -pre-processing and steps 3-4 as -assembling. - -Fortunately, almost all this detail is hidden from you, as -cc is a front end that manages calling all these programs -with the right arguments for you; simply typing -$ cc foobar.c - -will cause foobar.c to be compiled by all the -steps above. If you have more than one file to compile, just do -something like -$ cc foo.c bar.c - - -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.In case you -didn't know, a binary sort is an efficient way of sorting things into -order and a bubble sort isn't. - -There are lots and lots of options for cc, which -are all in the man page. Here are a few of the most important ones, -with examples of how to use them. - - - - -The output name of the file. If you do not use this -option, cc will produce an executable called -a.out.The reasons for this are buried in -the mists of history. - - -$ cc foobar.c executable is a.out -$ cc -o foobar foobar.c executable is foobar - - - - - -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 Makefile. - - -$ cc -c foobar.c - - -This will produce an object file (not an -executable) called foobar.o. This can be linked -together with other object files into an executable. - - - - - - -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 very useful; the disadvantage -is that all this extra information makes the program much bigger. -Normally, you compile with while you are -developing a program and then compile a release -version without when you're satisfied it -works properly. - - -$ cc -g foobar.c - - -This will produce a debug version of the -program.Note, we didn't use the -flag to specify the executable name, so we will get an executable -called a.out. Producing a debug version called -foobar is left as an exercise for the -reader! - - - - - - -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 to specify a higher level of optimisation, -but this often exposes bugs in the compiler's optimiser. For -instance, the version of cc that comes with the -2.1.0 release of FreeBSD is known to produce bad code with the - option in some circumstances. - -Optimisation is usually only turned on when compiling a release -version. - - -$ cc -O -o foobar foobar.c - - -This will produce an optimised version of -foobar. - - - - - -The following three flags will force cc to -check that your code complies to the relevant international standard, -often referred to as the ANSI standard, though -strictly speaking it is an ISO standard. - - - - - -Enable all the warnings which the authors of -cc believe are worthwhile. Despite the name, it -will not enable all the warnings cc is capable -of. - - - - - - -Turn off most, but not all, of the non-ANSI C -features provided by cc. Despite the name, it does -not guarantee strictly that your code will comply to the -standard. - - - - - - - -Turn off all -cc's non-ANSI C features. - - - - - -Without these flags, cc 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 portable code. - -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? - - -$ cc -Wall -ansi -pedantic -o foobar foobar.c - - -This will produce an executable foobar -after checking foobar.c for standard -compliance. - - - - - -Specify a function library to be used during when -linking. - -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. - -The rule is that if the library is called -libsomething.a, you -give cc the argument -. For example, -the math library is libm.a, so you give -cc the argument . A common -gotcha with the math library is that it has to be the -last library on the command line. - - -$ cc -o foobar foobar.c -lm - - -This will link the math library functions into -foobar. - -If you are compiling C++ code, you need to add -, or if you are using -FreeBSD 2.2 or later, to the command line argument to link the C++ -library functions. Alternatively, you can run c++ -instead of cc, which does this for you. -c++ can also be invoked as g++ -on FreeBSD. - - -$ cc -o foobar foobar.cc -lg++ For FreeBSD 2.1.6 and earlier -$ cc -o foobar foobar.cc -lstdc++ For FreeBSD 2.2 and later -$ c++ -o foobar foobar.cc - - -Each of these will both produce an executable -foobar from the C++ source file -foobar.cc. Note that, on Unix systems, C++ -source files traditionally end in .C, -.cxx or .cc, rather than -the MS-DOS style .cpp -(which was already used for something else). gcc -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 .cpp with -impunity! - - - - - - -Common <command>cc</command> Queries and Problems - -Q. I am trying to write a program which uses the -sin() function and I get an error like this. -What does it mean? - -/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - - - -A. When using mathematical functions like -sin(), you have to tell cc to -link in the math library, like so: - -$ cc -o foobar foobar.c -lm - - -Q. All right, I wrote this simple program to practice using -. All it does is raise 2.1 to the power of 6. - -#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -} - -and I compiled it as: - -$ cc temp.c -lm - -like you said I should, but I get this when I run it: - -$ ./a.out -2.1 ^ 6 = 1023.000000 - - - -This is not the right answer! What is -going on? - -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 int, which is -definitely not what you want here. - -Q. So how do I fix this? - -A. The prototypes for the mathematical functions are in -math.h. If you include this file, the compiler -will be able to find the prototype and it will stop doing strange -things to your calculation! - -#include <math.h> -#include <stdio.h> - -int main() { -... - - - -After recompiling it as you did before, run it: - -$ ./a.out -2.1 ^ 6 = 85.766121 - - - -If you are using any of the mathematical functions, -always include math.h and -remember to link in the math library. - -Q. I compiled a file called foobar.c and I -cannot find an executable called foobar. Where's -it gone? - -A. Remember, cc will call the executable -a.out unless you tell it differently. Use the - option: - -$ cc -o foobar foobar.c - - - -Q. OK, I have an executable called foobar, -I can see it when I run ls, but when I type in -foobar at the command prompt it tells me there is -no such file. Why can it not find it? - -A. Unlike MS-DOS, 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 -./foobar, which means run the file called -foobar in the current directory, or -change your PATH -environment variable so that it looks something like - -bin:/usr/bin:/usr/local/bin:. - -The dot at the end means look in the current directory if it is not in -any of the others. - -Q. I called my executable test, but -nothing happens when I run it. What is going on? - -A. Most Unix systems have a program called -test in /usr/bin and the -shell is picking that one up before it gets to checking the current -directory. Either type: - -$ ./test - -or choose a better name for your program! - -Q. I compiled my program and it seemed to run all right at -first, then there was an error and it said something about core -dumped. What does that mean? - -A. The name core dump 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 core, which the programmer -could then pore over to find out what went wrong. - -Q. Fascinating stuff, but what I am supposed to do now? - -A. Use gdb to analyse the core (see ). - -Q. When my program dumped core, it said something about a -segmentation fault. What's that? - -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. - -Common causes for this are: - -Trying to write to a NULL pointer, eg -char *foo = NULL; -strcpy(foo, "bang!"); - - -Using a pointer that hasn't been initialised, eg -char *foo; -strcpy(foo, "bang!"); -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. - -Trying to access past the end of an array, eg -int bar[20]; -bar[27] = 6; - - Trying to store something in read-only memory, eg -char *foo = "My string"; -strcpy(foo, "bang!"); -Unix compilers often put string literals like -"My string" into -read-only areas of memory. - -Doing naughty things with -malloc() and free(), eg -char bar[80]; -free(bar); -or -char *foo = malloc(27); -free(foo); -free(foo); - - - - -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. - -Q. Sometimes when I get a core dump it says bus -error. It says in my Unix book that this means a hardware -problem, but the computer still seems to be working. Is this -true? - -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. - -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? - -A. Yes, just go to another console or xterm, do -$ ps -to find out the process ID of your program, and do -$ kill -ABRT pid -where pid is the -process ID you looked up. - -This is useful if your program has got stuck in an infinite -loop, for instance. If your program happens to trap -SIGABRT, there are several other signals which have -a similar effect. - - - - - - -Make - - -What is <command>make</command>? - -When you're working on a simple program with only one or two source -files, typing in -$ cc file1.c file2.c -is not too bad, but it quickly becomes very tedious when there are -several files—and it can take a while to compile, too. - -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: -$ cc file1.o file2.o … file37.c &hellip -if we'd changed file37.c, 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. - -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. - -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? - -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. - -This program is called make. It reads in a -file, called a makefile, 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 if fromboz.o is older than -fromboz.c, that means someone must have changed -fromboz.c, so it needs to be -re-compiled. The makefile also has rules telling make -how to re-compile the source file, making it a -much more powerful tool. - -Makefiles are typically kept in the same directory as the -source they apply to, and can be called -makefile, Makefile or -MAKEFILE. Most programmers use the name -Makefile, as this puts it near the top of a -directory listing, where it can easily be seen.They -don't use the MAKEFILE form as block capitals -are often used for documentation files like -README. - - - - -Example of using <command>make</command> - -Here's a very simple make file: -foo: foo.c - cc -o foo foo.c -It consists of two lines, a dependency line and a creation line. - -The dependency line here consists of the name of the program -(known as the target), followed by a colon, -then whitespace, then the name of the source file. When -make reads this line, it looks to see if -foo exists; if it exists, it compares the time -foo was last modified to the time -foo.c was last modified. If -foo does not exist, or is older than -foo.c, it then looks at the creation line to -find out what to do. In other words, this is the rule for working out -when foo.c needs to be re-compiled. - -The creation line starts with a tab (press the -tab key) and then the command you would type to -create foo if you were doing it at a command -prompt. If foo is out of date, or does not -exist, make then executes this command to create -it. In other words, this is the rule which tells make how to -re-compile foo.c. - -So, when you type make, it will make -sure that foo is up to date with respect to your -latest changes to foo.c. This principle can be -extended to Makefiles with hundreds of -targets—in fact, on FreeBSD, it is possible to compile the -entire operating system just by typing make -world in the appropriate directory! - -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: -foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me - -We can tell make which target we want to make by typing: -$ make target -make will then only look at that target and ignore any -others. For example, if we type make foo with the -makefile above, make will ignore the install target. - -If we just type make on its own, make -will always look at the first target and then stop without looking at -any others. So if we typed make here, it will -just go to the foo target, re-compile -foo if necessary, and then stop without going on -to the install target. - -Notice that the install 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 make install. In this case, it will -copy foo 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. - -This is a slightly confusing subject to try and explain. If you -don't quite understand how make works, the best -thing to do is to write a simple program like hello -world 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 touch command is -very useful here—it changes the date on a file without you -having to edit it. - - - - -FreeBSD Makefiles - -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 -Makefile: -MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk> - -Now, if we go to the directory for this port and type -make, the following happens: - - -A check is made to see if the source code for this port is -already on the system. - -If it isn't, an FTP connection to the URL in -MASTER_SITES is set up to download the -source. - -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. - -Any changes required to make the source work on FreeBSD are -applied—this is known as patching. - -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). - -The source code for the program is compiled. In effect, -we change to the directory where the source was unpacked and do -make—the program's own make file has the -necessary information to build the program. - -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 make install. 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 package -database, so that the port can easily be uninstalled later -if we change our mind about it. - - - -Now I think you'll agree that's rather impressive for a four -line script! - -The secret lies in the last line, which tells -make to look in the system makefile called -bsd.port.mk. It's easy to overlook this line, -but this is where all the clever stuff comes from—someone has -written a makefile that tells make 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! - -If you want to have a look at these system makefiles, they're -in /usr/share/mk, 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!) - - - - -More advanced uses of <command>make</command> - -Make is a very powerful tool, and can do much -more than the simple example above shows. Unfortunately, there are -several different versions of make, 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. - -The version of make that comes with FreeBSD is the Berkeley -make; there is a tutorial for it in -/usr/share/doc/psd/12.make. To view it, do -$ zmore paper.ascii.gz -in that directory. - -Many applications in the ports use GNU -make, which has a very good set of info -pages. If you have installed any of these ports, GNU -make will automatically have been installed as -gmake. It's also available as a port and package -in its own right. - -To view the info pages for GNU make, -you will have to edit the dir file in the -/usr/local/info directory to add an entry for -it. This involves adding a line like - * Make: (make). The GNU Make utility. -to the file. Once you have done this, you can type -info and then select -make from the menu (or in -Emacs, do C-h -i). - - - - - -Debugging - - -The Debugger - -The debugger that comes with FreeBSD is called -gdb (GNU -debugger). You start it up by typing -$ gdb progname -although most people prefer to run it inside -Emacs. You can do this by: -M-x gdb RET progname RET - -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. - -gdb 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. - -Finally, if you find its text-based command-prompt style -off-putting, there's a graphical front-end for it xxgdb -in the ports collection. - -This section is intended to be an introduction to using -gdb and does not cover specialised topics such as -debugging the kernel. - - - - -Running a program in the debugger - -You'll need to have compiled the program with the - option to get the most out of using -gdb. 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: -… (no debugging symbols found) …when -gdb starts up, you'll know that the program wasn't -compiled with the option. - -At the gdb prompt, type break -main. 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 run 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 -main(). (If you've ever wondered where -main() gets called from, now you know!). - -You can now step through the program, a line at a time, by -pressing n. If you get to a function call, you can -step into it by pressing s. Once you're in a -function call, you can return from stepping into a function call by -pressing f. You can also use up and -down to take a quick look at the caller. - -Here's a simple example of how to spot a mistake in a program -with gdb. This is our program (with a deliberate -mistake): -#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; -} - - -This program sets i to be 5 -and passes it to a function bazz() which prints -out the number we gave it. - -When we compile and run the program we get -$ cc -g -o temp temp.c -$ ./temp -This is my program -anint = 4231 - -That wasn't what we expected! Time to see what's going -on!$ gdb temp -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) break main Skip the set-up code -Breakpoint 1 at 0x160f: file temp.c, line 9. gdb puts breakpoint at main() -(gdb) run Run as far as main() -Starting program: /home/james/tmp/temp Program starts running - -Breakpoint 1, main () at temp.c:9 gdb stops at main() -(gdb) n Go to next line -This is my program Program prints out -(gdb) s step into bazz() -bazz (anint=4231) at temp.c:17 gdb displays stack frame -(gdb) - - -Hang on a minute! How did anint get to be -4231? Didn't we set it to be 5 -in main()? Let's move up to -main() and have a look. - -(gdb) up Move up call stack -#1 0x1625 in main () at temp.c:11 gdb displays stack frame -(gdb) p i Show us the value of i -$1 = 4231 gdb displays 4231 -Oh dear! Looking at the code, we forgot to initialise -i. We meant to put -… -main() { - int i; - - i = 5; - printf("This is my program\n"); -&hellip -but we left the i=5; line out. As we didn't -initialise i, it had whatever number happened to be -in that area of memory when the program ran, which in this case -happened to be 4231. - -gdb displays the stack frame -every time we go into or out of a function, even if we're using -up and down 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). - - - - -Examining a core file - -A core file is basically a file which contains the complete -state of the process when it crashed. In the good old -days, 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 progname.core instead of just -core, to make it clearer which program a core -file belongs to. - -To examine a core file, start up gdb in the -usual way. Instead of typing break or -run, type -(gdb) core progname.core -If you're not in the same directory as the core file, you'll have to -do dir /path/to/core/file first. - -You should see something like this: -$ gdb a.out -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) core a.out.core -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) - -In this case, the program was called -a.out, so the core file is called -a.out.core. 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 bazz. - -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 bt command causes -gdb to print out a back-trace of the call -stack: -(gdb) bt -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb)The end() function is called when -a program crashes; in this case, the bazz() -function was called from main(). - - - - -Attaching to a running program - -One of the neatest features about gdb 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. - -What you do is start up another gdb, use -ps to find the process ID for the child, and -do(gdb) attach pid -in gdb, and then debug as usual. - -That's all very well, you're probably thinking, -but by the time I've done that, the child process will be over -the hill and far away. Fear not, gentle reader, here's how to -do it (courtesy of the gdb info pages): -&hellip -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 */ - &hellip -} else { /* parent */ - &hellip -Now all you have to do is attach to the child, set -PauseMode to 0, and -wait for the sleep() call to return! - - - - - -Using Emacs as a Development Environment - - -Emacs - -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.At least, not unless you pay out very large sums -of money. 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. - -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. - -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. - -It's impossible even to summarise everything Emacs can do here, but -here are some of the features of interest to developers: - - -Very powerful editor, allowing search-and-replace on -both strings and regular expressions (patterns), jumping to start/end -of block expression, etc, etc. - -Pull-down menus and online help. - -Language-dependent syntax highlighting and -indentation. - -Completely customisable. - -You can compile and debug programs within -Emacs. - -On a compilation error, you can jump to the offending -line of source code. - -Friendly-ish front-end to the info -program used for reading GNU hypertext documentation, including the -documentation on Emacs itself. - -Friendly front-end to gdb, -allowing you to look at the source code as you step through your -program. - -You can read Usenet news and mail while your program -is compiling. - -And doubtless many more that I've overlooked. - -Emacs can be installed on FreeBSD using the Emacs -port. - -Once it's installed, start it up and do C-h -t to read an Emacs tutorial—that means hold down -the control key, press h, let go of -the control key, and then press t. -(Alternatively, you can you use the mouse to select Emacs -Tutorial from the Help menu). - -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 -M-x replace-s RET foo RET bar RET -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. - -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. - -If you can't remember what a particular combination of keys -does, select Describe Key from the -Help menu and type it in—Emacs will tell you -what it does. You can also use the Command -Apropos menu item to find out all the commands which -contain a particular word in them, with the key binding next to -it. - -By the way, the expression above means hold down the -Meta key, press x, release the -Meta key, type replace-s -(short for replace-string—another feature of -Emacs is that you can abbreviate commands), press the -return key, type foo (the -string you want replaced), press the return key, -type bar (the string you want to replace foo with) -and press return again. Emacs will then do the -search-and-replace operation you've just requested. - -If you're wondering what on earth the Meta key -is, it's a special key that many Unix workstations have. -Unfortunately, PC's don't have one, so it's usually the -alt key (or if you're unlucky, the escape -key). - -Oh, and to get out of Emacs, do C-x C-c -(that means hold down the control key, press -x, press c and release the -control 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 C-z 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). - - - - -Configuring Emacs - -Emacs does many wonderful things; some of them are built in, -some of them need to be configured. - -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!). - -The best way to learn Emacs Lisp is to download the Emacs -Tutorial - -However, there's no need to actually know any Lisp to get -started with configuring Emacs, as I've included a sample -.emacs 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. - - - - -A sample <filename>.emacs</filename> file - -Unfortunately, there's far too much here to explain it in detail; -however there are one or two points worth mentioning. - - - - -Everything beginning with a ; is a -comment and is ignored by Emacs. - -In the first line, the --*- Emacs-Lisp -*- is so that we can -edit the .emacs 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 -.emacs. - -The tab 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 -tab character in whatever you're writing, hold the -control key down while you're pressing the -tab key. - -This file supports syntax highlighting for C, C++, -Perl, Lisp and Scheme, by guessing the language from the -filename. - -Emacs already has a pre-defined function called -next-error. In a compilation output window, this -allows you to move from one compilation error to the next by doing -M-n; we define a complementary function, -previous-error, that allows you to go to a -previous error by doing M-p. The nicest feature of -all is that C-c C-c will open up the source file -in which the error occurred and jump to the appropriate -line. - - 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 -$ emacsclient filename -and then you can edit the file in your Emacs!Many -Emacs users set their EDITOR environment to -emacsclient so this happens every time they need -to edit a file. - - - - - -A sample <filename>.emacs</filename> file -;; -*-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") - -(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))) - -;; 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) ".") - - - - - - -Extending the Range of Languages Emacs Understands - -Now, this is all very well if you only want to program in the -languages already catered for in the .emacs file -(C, C++, Perl, Lisp and Scheme), but what happens if a new language -called whizbang comes out, full of exciting -features? - -The first thing to do is find out if whizbang -comes with any files that tell Emacs about the language. These -usually end in .el, short for Emacs -Lisp. For example, if whizbang is a FreeBSD -port, we can locate these files by doing -$ find /usr/ports/lang/whizbang -name "*.el" -print -and install them by copying them into the Emacs site Lisp directory. On -FreeBSD 2.1.0-RELEASE, this is -/usr/local/share/emacs/site-lisp. - -So for example, if the output from the find command was -/usr/ports/lang/whizbang/work/misc/whizbang.el -we would do -$ cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp - - -Next, we need to decide what extension whizbang source files -have. Let's say for the sake of argument that they all end in -.wiz. We need to add an entry to our -.emacs file to make sure Emacs will be able to -use the information in whizbang.el. - -Find the auto-mode-alist entry in -.emacs and add a line for whizbang, such -as: -… -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -… -This means that Emacs will automatically go into -whizbang-mode when you edit a file ending in -.wiz. - -Just below this, you'll find the -font-lock-auto-mode-list entry. Add -whizbang-mode to it like so: -;; 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") -This means that Emacs will always enable -font-lock-mode (ie syntax highlighting) when -editing a .wiz file. - -And that's all that's needed. If there's anything else you want -done automatically when you open up a .wiz file, -you can add a whizbang-mode hook (see -my-scheme-mode-hook for a simple example that -adds auto-indent). - - - - - -Further Reading - - -Brian Harvey and Matthew Wright -Simply Scheme -MIT 1994. -ISBN 0-262-08226-8 - -Randall Schwartz -Learning Perl -O'Reilly 1993 -ISBN 1-56592-042-2 - -Patrick Henry Winston and Berthold Klaus Paul Horn -Lisp (3rd Edition) -Addison-Wesley 1989 -ISBN 0-201-08319-1 - -Brian W. Kernighan and Rob Pike -The Unix Programming Environment -Prentice-Hall 1984 -ISBN 0-13-937681-X - -Brian W. Kernighan and Dennis M. Ritchie -The C Programming Language (2nd Edition) -Prentice-Hall 1988 -ISBN 0-13-110362-8 - -Bjarne Stroustrup -The C++ Programming Language -Addison-Wesley 1991 -ISBN 0-201-53992-6 - -W. Richard Stevens -Advanced Programming in the Unix Environment -Addison-Wesley 1992 -ISBN 0-201-56317-7 - -W. Richard Stevens -Unix Network Programming -Prentice-Hall 1990 -ISBN 0-13-949876-1 - - - - - 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 @@ - - - - - - -Formatting Media For Use With FreeBSD 2.2-RELEASE -A Tutorial - - - -Doug -White - -
dwhite@resnet.uoregon.edu
- - - - -March 1997 -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. - - - - - -Introduction & Definitions - - -Overview -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. - -There are two possible modes of disk formatting: - - -compatibility mode: Arranging a -disk so that it has a slice table for use with other operating -systems. - -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. - - - -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. - -In addition to selecting the mode, two methods of slicing the -disk are available. One is using the system installation tool -/stand/sysinstall. 2.1.7-RELEASE and later -versions of sysinstall 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 sysinstall requires some manipulation. - - -Definitions - -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. - - - - -compatibility mode: Arranging a disk so that it has a slice -table for use with other operating systems. Oppose dangerously -dedicated mode. - -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. - -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. - -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 slice table 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. - -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. - -sector: Smallest subdivision of a disk. One sector usually -represents 512 bytes of data. - - - - - -Warnings & Pitfalls - -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. - -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. - -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! - - - - -Zip, Jaz, and Other Removables - -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 dmesg -output and make sure your device and the disk's size is listed. If -the kernel reports - - -Can't get the size - - -then the disk was not in the drive. In this case, you will need to restart the -machine before attempting to format disks. - - - - - -Formatting Disks in Dedicated Mode - - -Introduction - -This section details how to make disks that are totally dedicated to -FreeBSD. Remember, dedicated mode disks cannot be booted by the PC -architecture. - - - -Making Dedicated Mode Disks using Sysinstall - -/stand/sysinstall, 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. - - -Start sysinstall as root by typing - -/stand/sysinstall - -from the command prompt. - -Select Index. -Select Partition. -Select the disk to edit with arrow keys and -SPACE. - -If you are using this entire disk for FreeBSD, select -A. -When asked: - - -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)? - -answer No. -When asked if you still want to do this, answer -Yes. -Select Write. -When warned about Writing on installed systems, answer -Yes. -Quitthe FDISK Editor and -ESCAPE back to the Index menu. -Select Label from the Index -menu. -Label as desired. For a single partition, enter -C to Create a partition, accept the -default size, partition type Filesystem, and a mountpoint (which isn't -used). -Enter W 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: - -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - -Ignore. - -Exit out by repeatedly pressing ESCAPE. - - - - -Making Dedicated Mode Disks Using the Command Line - - -Execute the following commands, replacing wd2 with the disk -name. Lines beginning with # are comments. - - - - 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 - - - - - If you need to edit the disklabel to create multiple -partitions (such as swap), use the following: - - - - - 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 - - - - -Your disk is now ready for use. - - - - - -Making Compatibility Mode Disks - - -Introduction -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. - - - - -Making Compatibility Mode Disks Using Sysinstall - - -Start sysinstall as root by typing - -/stand/sysinstall - -from the command prompt. - -Select Index. -Select Partition. -Select the disk to edit with arrow keys and -SPACE. - -If you are using this entire disk for FreeBSD, select -A. - -When asked: - - -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)? - - answer yes. -Select Write. -When asked to install the boot manager, select None with -SPACE then hit ENTER for OK. -Quit the FDISK Editor. -You'll be asked about the boot manager, select -None -again. -Select Label from the Index -menu. -Label as desired. For a single partition, accept the -default size, type filesystem, and a mountpoint (which isn't -used). -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: - - -Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - -Ignore. - -Exit out by repeatedly pressing ESCAPE. - - -Your new disk is now ready for use. - - - - - -Other Disk Operations - -Adding Swap Space - -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. - -To add swap space when adding a disk to a system: - -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. -When newfsing the drive, do NOT newfs the `c' -partition. Instead, newfs the partition where the non-swap space -lies. -Add an entry to /etc/fstab as follows: - - -/dev/wd0b none swap sw 0 0 - - -Change /dev/wd0b to the device of the newly added -space. -To make the new space immediately available, use the -swapon command. - - - -$ swapon /dev/sd0b - -swapon: added /dev/sd0b as swap space - - - - - - - - -Copying the Contents of Disks - -Submitted By: Renaud Waldura (renaud@softway.com) - -To move file from your original base disk to the fresh new one, -do: - - - -mount /dev/wd2 /mnt -pax -r -w -p e /usr/home /mnt -umount /mnt -rm -rf /usr/home/* -mount /dev/wd2 /usr/home - - - - - - - -Creating Striped Disks using CCD -Commands Submitted By: Stan Brown (stanb@awod.com) - - -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 -CCD Homepage for further details. - -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 identical. - -Before executing these commands, make sure you add the line - -pseudo-device ccd 4 - - -to your kernel. - - - - -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 - - - - -Now you can mount and use your CCD by referencing device /dev/ccd0c. - - - - - - -Credits - - - -The author would like to thank the following individuals for -their contributions to this project: - -Darryl Okahata -(darrylo@hpnmhjw.sr.hp.com) for his -simple dedicated mode setup documentation which I have used repeatedly -on freebsd-questions. -Jordan Hubbard -(jkh@freebsd.org) for making -sysinstall useful for this type of task. -John Fieber -(jfieber@indiana.edu) for making -information and examples of the DocBook DTD on which this document is -based. -Greg Lehey (grog@freebsd.org) for checking my -work and pointing out inaccuracies, as well as miscellaneous support. - - - - - - - - - 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 @@ - - - - - - - - -Diskless X Server: a how to guide - - - - Jerry -Kendall - -
-jerry@kcis.com -
- - - -28-December-1996 - - -1996 -Jerry Kendall - - - - -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. - - - -NOTE: I am sure that there is stuff that needs to be added to this. Please send me any comments.... - - - - - - - - - -Creating the boot floppy (On the diskless system) - -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. - - ---- 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 - ---- - - - -Getting the network boot programs (On the server) - -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. - - -Determine which program to run (On the diskless system) - -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. - - -Booting across the network - -Boot the diskless system with out any config.sys/autoexec.bat -files. try running the boot program for your Ethernet adapter. - - 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.. - -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. - - -Allowing systems to boot across the network (On the - server) - -Make sure the /etc/inetd.conf file has entries for tftp and bootps. -Mine are listed below: - - ---- /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 - ---- - -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. - -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. - -Add an entry to /etc/bootptab (maybe creating the file). It should be -laid out identical to this: - - - 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... - -NOTE: -****** Be sure to setup the IP addresses correctly, the addresses -above are my own...... - -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: - - - ---- /tftpboot/cfg.199.246.76.2 ---- - rootfs 199.246.76.1:/DiskLess/rootfs/altair - hostname altair.kcis.com - ---- - -The line 'hostname altair.kcis.com' simply tells the diskless -system what its fully qualified domain name is. - -The line 'rootfs 199.246.76.1:/DiskLess/rootfs/altair' tells the -diskless system where its NFS mountable root filesystem is located. - -NOTE:!!!!! The NFS mounted root filesystem will be mounted READ ONLY. - -The hierarchy for the diskless system can be re-mounted allowing -read-write operations if required. - -I use my spare 386DX-40 as a dedicated X terminal... - -The hierarchy for 'altair' is: - - - / - /bin - /etc - /tmp - /sbin - /dev - /dev/fd - /usr - /var - /var/run - - -The actual list of files is: - - - -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 - -Don't forget to 'MAKEDEV all' in the 'dev' directory. - -My /etc/rc for 'altair' is: - - - #!/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 - - -Any comments and ALL questions welcome.... - - - 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 @@ -
-
- freebsd-questions@freebsd.org -
- 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 @@ - - - - - - - - - - - - - -
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 @@ - - - -%man; - - %chapters; -]> - - - - FreeBSD Documentation Project Primer for New Contributors - - - Nik - Clayton - -
nik@FreeBSD.ORG
- - - - - 1998 - 1999 - Nik Clayton - - - $Date: 1999-07-14 22:31:28 $ - - $Id: book.sgml,v 1.5 1999-07-14 22:31:28 nik Exp $ - - - 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: - - - - 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. - - - - 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. - - - - - Thank you for becoming a part of the FreeBSD Documentation - Project. Your contribution is extremely valuable. - - 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. - - This document is a work in progress, and is not complete. Sections - that are known to be incomplete are indicated with a - * in their name. - - - - - Preface - - - Shell Prompts - - 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. - - - - - - User - Prompt - - - - - - Normal user - &prompt.user; - - - - root - &prompt.root; - - - - - - - - Typographic Conventions - - The following table describes the typographic conventions used in - this book. - - - - - - Meaning - Examples - - - - - - The name of commands, files, and directories. On screen - computer output. - Edit your .login - file.Use ls -a to list all - files.You have mail. - - - - - What you type, when contrasted with on-screen computer - output. - - &prompt.user; su -Password: - - - - Manual page references. - - Use - su - 1 - to change user names. - - - - User and group names - - Only root can do this. - - - - Emphasis - - You must do this. - - - - Command line variables; replace with the real name or - variable. - - To delete a file, type rm filename - - - - Environment variables - - $HOME is your home directory. - - - - - - - - Notes, warnings, and examples - - Within the text appear notes, warnings, and examples. - - - Notes are represented like this, and contain information that - you should take note of, as it may affect what you do. - - - - 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. - - - - A sample example - - 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. - - - - - Acknowledgments - - 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. - - - - &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; - - - - 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 @@ - 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 @@ - - - - - - - - - - - - - - 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 @@ - - - - Overview - - 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. - - This document's main purpose is to clearly explain how - the FDP is organised, how to write and submit - documentation to the FDP, and how to - effectively use the tools available to you when writing - documentation. - - 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 - freebsd-doc@freebsd.org mailing list. - - After you have finished reading this document you should: - - - - Know which documentation is maintained by the FDP. - - - - Be able to read and understand the SGML source code for the - documentation maintained by the FDP. - - - - Be able to make changes to the documentation. - - - - Be able to submit your changes back for review and eventual - inclusion in the FreeBSD documentation. - - - - - The FreeBSD Documentation Set - - The FDP is responsible for four categories of FreeBSD - documentation. - - - - Manual pages - - - 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. - - The translation teams are responsible for translating the - system manual pages in to different languages. These translations - are kept within the FDP. - - - - - FAQ - - - 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. - - - - - Handbook - - - The Handbook aims to be the comprehensive on-line resource and - reference for FreeBSD users. - - - - - Web site - - - This is the main FreeBSD presence on the World Wide Web, - visible at http://www.freebsd.org/ - and many mirrors around the world. The web site is many people's - first exposure to FreeBSD. - - - - - 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 - CVSup or - CTM to keep their own local copies of - this documentation. - - 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. - - - - Before you start - - This document assumes that you already know: - - - - 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 CVS - and either CVSup or - CTM) or by using - CVSup to download just a - checked-out copy. - - - - How to download and install new software using either the - FreeBSD Ports system or &man.pkg.add.1;. - - - - - - - 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 @@ - - - - Using <literal>sgml-mode</literal> with - <application>Emacs</application> - - Recent versions of Emacs or Xemacs (available from the ports - collection) contain a very useful package called PSGML. Automatically - invoked when a file with .sgml extension is loaded, - or by typing M-x sgml-mode, it is a major mode for - dealing with SGML files, elements and attributes. - - An understanding of some of the commands provided by this mode can - make working with SGML documents such as the Handbook much easier. - - - - C-c C-e - - - Runs sgml-insert-element. 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. - - 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. - - - - - C-c = - - - Runs sgml-change-element-name. 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. - - - - - C-c C-r - - - Runs sgml-tag-region. 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. - - - - - C-c - - - - Runs sgml-untag-element. 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. - - - - - C-c C-q - - - Runs sgml-fill-element. Will recursively fill - (i.e., reformat) content from the current element in. The filling - will affect content in which whitespace is - significant, such as within programlisting - elements, so run this command with care. - - - - - C-c C-a - - - Runs sgml-edit-attributes. 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, C-k to remove an existing - value and replace it with a new one, C-c to close - this buffer and return to the main document. - - - - - C-c C-v - - - Runs sgml-validate. 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. - - - - - Doubtless there are other useful functions of this mode, but those are - the ones I use most often. - - - - - 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 @@ - - - - See Also - - 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. - - - The FreeBSD Documentation Project - - - - The FreeBSD - Documentation Project web pages - - - - The FreeBSD Handbook - - - - - - SGML - - - - The SGML/XML web - page, a comprehensive SGML resource - - - - Gentle introduction to SGML - - - - - - HTML - - - - The World Wide Web - organisation - - - - The HTML 4.0 - specification - - - - - - DocBook - - - - The Davenport - Group, maintainers of the DocBook DTD - - - - - - The Linux Documentation Project - - - - The Linux Documentation - Project web pages - - - - - - - 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 @@ - - - - SGML Markup - - 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. - - 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. - - This is not 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 - freebsd-doc@freebsd.org. - - - Inline vs. block - - In the remainder of this document, when describing elements, - inline means that the element can occur within a - block element, and does not cause a line break. A - block element, by comparison, will cause a line - break (and other processing) when it is encountered. - - - - HTML - - HTML, the HyperText Markup Language, is the markup language of - choice on the World Wide Web. More information can be found at - <URL:http://www.w3.org/>. - - 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. - - HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the - latest, 4.0 (available in both strict and - loose variants). - - The HTML DTDs are available from the ports collection in the - textproc/html port. They are automatically - installed as part of the textproc/docproj - port. - - - Formal Public Identifier (FPI) - - 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. - - The majority of HTML documents on the FreeBSD web site comply with - the loose version of HTML 4.0. - - -PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" - - - - Sectional elements - - An HTML document is normally split in to two sections. The first - section, called the head, 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 - body, contains the content that will be displayed - to the user. - - These sections are indicated with head and - body elements respectively. These elements are - contained within the top-level html element. - - - Normal HTML document structure - - -<html> - <head> - <title>The document's title</title> - </head> - - <body> - - … - - </body> -</html> - - - - - Block elements - - - Headings - - HTML allows you to denote headings in your document, at up to - six different levels. - - The largest and most prominent heading is h1, - then h2, continuing down to - h6. - - The element's content is the text of the heading. - - - <sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc. - - Use: - - -First section - - - -

This is the heading for the first section

- - - -

This is the heading for the first sub-section

- - - -

This is the heading for the second section

- -]]> - - - Generally, an HTML page should have one first level heading - (h1). This can contain many second level - headings (h2), which can in turn contain many - third level headings. Each - hn element should have - the same element, but one further up the hierarchy, preceeding it. - Leaving gaps in the numbering is to be avoided. - - - Bad ordering of - <sgmltag>h<replaceable>n</replaceable></sgmltag> elements - - Use: - - -First section - - - -

Sub-section

- -]]> - - - - - Paragraphs - - HTML supports a single paragraph element, - p. - - - <sgmltag>p</sgmltag> - - Use: - - -This is a paragraph. It can contain just about any - other element.

]]> - - - - - Block quotations - - A block quotation is an extended quotation from another document - that should not appear within the current paragraph. - - - <sgmltag>blockquote</sgmltag> - - Use: - - -A small excerpt from the US Constitution;

- -
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.
]]> - - - - - Lists - - You can present the user with three types of lists, ordered, - unordered, and definition. - - 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. - - Ordered lists are indicated by the ol - element, unordered lists by the ul element, and - definition lists by the dl element. - - Ordered and unordered lists contain listitems, indicated by the - li element. A listitem can contain textual - content, or it may be further wrapped in one or more - p elements. - - Definition lists contain definition terms - (dt) and definition descriptions - (dd). A definition term can only contain inline - elements. A definition description can contain other block - elements. - - - <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag> - - Use: - - -An unordered list. Listitems will probably be - preceeded by bullets.

- -
    -
  • First item
    • - -
  • Second item
    • - -
  • Third item
    • -
- -

An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be - numbered.

- -
    -

  1. This is the first item. It only has one paragraph.

    2. - -

  2. This is the first paragraph of the second item.

    - -

    This is the second paragraph of the second item.

    3. - -

  3. This is the first and only paragraph of the third - item.

    4. -
]]> - - - - Definition lists with <sgmltag>dl</sgmltag> - - Use: - - - -
Term 1
- -

Paragraph 1 of definition 1.

- -

Paragraph 2 of definition 1.

- -
Term 2
- -

Paragraph 1 of definition 2.

- -
Term 3
- -
Paragraph 1 of definition 3. Note that the <p> - element is not required in the single paragraph case.
-]]> - - - - - Pre-formatted text - - 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. - - In order to do this, wrap the content in the - pre element. - - - <sgmltag>pre</sgmltag> - - You could use pre to mark up an e-mail - message; - - - - 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 - - - - Comments appreciated. - - N -]]> - - - - - Tables - - - 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. - - - Mark up tabular information using the table - element. A table consists of one or more table rows - (tr), each containing one or more cells of table - data (td). 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 - p element. - - - Simple use of <sgmltag>table</sgmltag> - - Use: - - -This is a simple 2x2 table.

- - - - - - - - - - - - - -
Top left cellTop right cell
Bottom left cellBottom right cell
]]> - - A cell can span multiple rows and columns. To indicate this, - add the rowspan and/or colspan - attributes, with values indicating the number of rows of columns - that should be spanned. - - - Using <literal>rowspan</literal> - - Use: - - -One tall thin cell on the left, two short cells next to - it on the right.

- - - - - - - - - - - -
Long and thin
Top cellBottom cell
]]> - - - - Using <literal>colspan</literal> - - Use: - - -One long cell on top, two short cells below it.

- - - - - - - - - - - -
Top cell
Bottom left cellBottom right cell
]]> - - - - Using <literal>rowspan</literal> and - <literal>colspan</literal> together - - Use: - - -On a 3x3 grid, the top left block is a 2x2 set of - cells merged in to one. The other cells are normal.

- - - - - - - - - - - - - - - - - - - - - -
Top left large cellTop right cell
Middle right cell
Bottom left cellBottom middle cellBottom right cell
]]> - - - - - - In-line elements - - - Emphasising information - - You have two levels of emphasis available in HTML, - em and strong. - em is for a normal level of emphasis and - strong indicates stronger emphasis. - - Typically, em is rendered in italic and - strong is rendered in bold. This is not always - the case however, and you should not rely on it. - - - <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag> - - Use: - - -This has been emphasised, while - this has been strongly emphasised.

]]> - - - - - Bold and italics - - Because HTML includes presentational markup, you can also - indicate that particular content should be rendered in bold or - italic. The elements are b and - i respectively. - - - <sgmltag>b</sgmltag> and <sgmltag>i</sgmltag> - - -This is in bold, while this is - in italics.

]]> - - - - - Indicating fixed pitch text - - If you have content that should be rendered in a fixed pitch - (typewriter) typeface, use tt (for - “teletype”). - - - <sgmltag>tt</sgmltag> - - Use: - - -This document was originally written by - Nik Clayton, who can be reached by e-mail as - nik@freebsd.org.

]]> - - - - - Content size - - You can indicate that content should be shown in a larger or - smaller font. There are three ways of doing this. - - - - Use big and small - around the content you wish to change size. These tags can be - nested, so <big><big>This is much - bigger</big></big> is possible. - - - - Use font with the size - attribute set to +1 or -1 - respectively. This has the same effect as using - big or small. However, - the use of this approach is deprecated. - - - - Use font with the size - attribute set to a number between 1 and 7. The default font size - is 3. This approach is deprecated. - - - - - <sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and - <sgmltag>font</sgmltag> - - The following fragments all do the same thing. - - -This text is slightly smaller. But - this text is slightly bigger.

- -

This text is slightly smaller. But - this text is slightly bigger - -

This text is slightly smaller. But - this text is slightly bigger.

]]> - - - - - - Links - - - Links are also in-line elements. - - - - Linking to other documents on the WWW - - 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. - - The link is indicated with a, and the - href 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). - - - Using <literal><a href="..."></literal> - - Use: - - -More information is available at the - FreeBSD web site.

]]> - - - These links will take the user to the top of the chosen - document. - - - - Linking to other parts of documents - - Linking to a point within another document (or within the same - document) requires that the document author include anchors that you - can link to. - - Anchors are indicated with a and the - name attribute instead of - href. - - - Using <literal><a name="..."></literal> - - Use: - - -This paragraph can be referenced - in other links with the name para1.

]]> - - - 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 - # symbol. - - - Linking to a named part of another document - - Assume that the para1 example resides in a - document called foo.html. - - -More information can be found in the - first paragraph of - foo.html.

]]> - - - 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 #). - - - Linking to a named part of another document - - Assume that the para1 example resides in - this document - - -More information can be found in the - first paragraph of this - document.

]]> - - - - - - - DocBook - - DocBook was designed by the Davenport Group to be - a DTD for writing technical documentation. As such, and unlike LinuxDoc - and HTML, DocBook is very heavily orientated towards markup that - describes what something is, rather than describing - how it should be presented. - - - <literal>formal</literal> vs. <literal>informal</literal> - - Some elements may exist in two forms, formal - and informal. 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. - - - The DocBook DTD is available from the ports collection in the - textproc/docbook port. It is automatically - installed as part of the textproc/docproj - port. - - - FreeBSD extensions - - 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. - - Where a FreeBSD specific element is listed below it is clearly - marked. - - Throughout the rest of this document, the term - “DocBook” is used to mean the FreeBSD extended DocBook - DTD. - - - 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 nik@freebsd.org. - - - - - Formal Public Identifier (FPI) - - In compliance with the DocBook guidelines for writing FPIs for - DocBook customisations, the FPI for the FreeBSD extended DocBook DTD - is; - - -PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" - - - - Sectional elements - - DocBook contains a number of elements for marking up the structure - of a book. - - Generally, the top level (first) element will be - book. - - A book is organised into chapters. This is a - mandatory requirement. There may be parts between - the book and the chapter to provide another layer of organisation. - The Handbook is arranged in this way. - - A chapter may (or may not) contain one or more sections. These - are indicated with the sect1 element. If a section - contains another section then use the sect2 - element, and so on, up to sect5. - - Chapters and sections contain the remainder of the content. - - - Starting a book - - The content of the book is contained within the - book 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. - - This additional information should be contained within - bookinfo. - - - Boilerplate <sgmltag>book</sgmltag> with - <sgmltag>bookinfo</sgmltag> - - - -<book> - <bookinfo> - <title>Your title here</title> - - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>Your e-mail address</email></address> - </affiliation> - </author> - - <copyright> - <year>1998</year> - <holder role="mailto:your e-mail address">Your name</holder> - </copyright> - - <pubdate role="rcs">$Date$</pubdate> - - <releaseinfo>$Id$</releaseinfo> - - <abstract> - <para>Include an abstract of the book's contents here.</para> - </abstract> - </bookinfo> - - … - -</book> - - - - - Indicating chapters - - Use chapter to mark up your chapters. Each - chapter has a mandatory title. - - - A simple chapter - - - - The chapter's title - - ... -]]> - - - A chapter can not be empty, it must contain elements in addition - to title. If you need to include an empty - chapter then just use an empty paragraph. - - - Empty chapters - - - - This is an empty chapter - - -]]> - - - - - Sections below chapters - - Chapters can be broken up into sections, subsections, and so - on. Use the sectn - element. The n indicates the section - number, which identifies the section level. - - The first sectn is - sect1. You can have one or more of these in a - chapter. They can contain one or more sect2 - elements, and so on, down to sect5. - - - Sections in chapters - - - - A sample chapter - - Some text in the chapter. - - - First section (1.1) - - ... - - - - Second section (1.2) - - - First sub-section (1.2.1) - - - First sub-sub-section (1.2.1.1) - - ... - - - - - Second sub-section (1.2.2) - - ... - - -]]> - - - - - Subdividing using <sgmltag>part</sgmltag>s - - You can introduce another layer of organisation between - book and chapter with one or - more parts. - - - - Introduction - - - Overview - - ... - - - - What is FreeBSD? - - ... - - - - History - - ... - -]]> - - - - - Block elements - - - Paragraphs - - DocBook supports three types of paragraphs; - formalpara, para, and - simpara. - - Most of the time you will only need to use - para. formalpara includes a - title element, and simpara - disallows some elements from within para. Stick - with para. - - - <sgmltag>para</sgmltag> - - Use: - - -This is a paragraph. It can contain just about any - other element. ]]> - - Appearance: - - This is a paragraph. It can contain just about any other - element. - - - - - Block quotations - - 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. - - Blockquotes can optionally contain a title and an attribution - (or they can be left untitled and unattributed). - - - <sgmltag>blockquote</sgmltag> - - Use: - - -A small excerpt from the US Constitution; - -
- 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 - - Copied from a web site somewhere - - 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. -
- - - - - Tips, notes, warnings, cautions, important information and - sidebars. - - 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. - - Depending on the nature of the information, one of - tip, note, - warning, caution, and - important should be used. Alternatively, if the - information is related to the main text but is not one of the above, - use sidebar. - - The circumstances in which to choose one of these elements over - another is unclear. The DocBook documentation suggests; - - - - A Note is for information that should be heeded by all - readers. - - - - An Important element is a variation on Note. - - - - A Caution is for information regarding possible data loss - or software damage. - - - - A Warning is for information regarding possible hardware - damage or injury to life or limb. - - - - - <sgmltag>warning</sgmltag> - - Use: - - - - Installing FreeBSD may make you want to delete Windows from your - harddisk. -]]> - - - - - Installing FreeBSD may make you want to delete Windows from - your harddisk. - - - - - Lists and procedures - - 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. - - In order to do this, use itemizedlist, - orderedlist, or - procedureThere are other types of - list element in DocBook, but we're not concerned with those at - the moment. - - - - itemizedlist and - orderedlist are similar to the counterparts in - HTML, ul and ol. Each one - consists of one or more listitem elements, and - each listitem contains one or more block - elements. The listitem elements are analagous to - HTMLs li tags. However, unlike HTML they are - required. - - procedure is slightly different. It consists - of steps, which may in turn consists of more - steps or substeps. Each - step contains block elements. - - - <sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, and - <sgmltag>procedure</sgmltag> - - Use: - - - - - This is the first itemized item. - - - - This is the second itemized item. - - - - - - This is the first ordered item. - - - - This is the second ordered item. - -]]> - - Appearance: - - - - This is the first itemized item. - - - - This is the second itemized item. - - - - - - This is the first ordered item. - - - - This is the second ordered item. - - - - - - - Showing file samples - - If you want to show a fragment of a file (or perhaps a complete - file) to the user, wrap it in the programlisting - element. - - White space and line breaks within - programlisting are - 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. - - - <sgmltag>programlisting</sgmltag> - - Use: - - -When you have finished, your program should look like - this; - - -#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}]]> - - Notice how the angle brackets in the - #include line need to be referenced by their - entities instead of being included literally. - - Appearance: - - When you have finished, your program should look like - this; - - -#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -} - - - - There is a mechanism within DocBook for referring to sections - of a previously occuring programlisting, called - callouts (see programlistingco 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. - - - - - Tables - - 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. - - In general terms (and see the DocBook documentation for more - detail) a table (which can be either formal or informal) consists of - a table element. This contains at least one - tgroup element, which specifies (as an attribute) - the number of columns in this table group. Within the tablegroup - you can then have one thead element, which - contains elements for the table headings (column headings), and one - tbody which contains the body of the - table. - - Both tgroup and thead - contain row elements, which in turn contain - entry elements. Each entry - element specifies one cell in the table. - - - <sgmltag>informaltable</sgmltag> - - Use: - - - - - - - This is column head 1 - This is column head 2 - - - - - - Row 1, column 1 - Row 1, column 2 - - - - Row 2, column 1 - Row 2, column 2 - - - -]]> - - Appearance: - - - - - - This is column head 1 - This is column head 2 - - - - - - Row 1, column 1 - Row 1, column 2 - - - - Row 2, column 1 - Row 2, column 2 - - - - - - - If you don't want a border around the table the - frame attribute can be added to the - informaltable element with a value of - none (i.e., <informaltable - frame="none">). - - - Tables where <literal>frame="none"</literal> - - Appearance: - - - - - - This is column head 1 - This is column head 2 - - - - - - Row 1, column 1 - Row 1, column 2 - - - - Row 2, column 1 - Row 2, column 2 - - - - - - - - - Examples for the user to follow - - 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. - - A number of distinct elements and entities come in to play - here. - - - - informalexample - - - 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 informalexample. For those times - when you do need to include a title on the example, use - example. - - - - - screen - - - Everything the user sees in this example will be on the - computer screen, so the next element is - screen. - - Within screen, white space is - significant. - - - - - prompt, - &prompt.root; and - &prompt.user; - - - 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 - prompt. - - 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 &prompt.root; and - &prompt.user; as necessary. They do - not need to be inside prompt. - - - &prompt.root; and - &prompt.user; are FreeBSD - extensions to DocBook, and are not part of the original - DTD. - - - - - - userinput - - - When displaying text that the user should type in, wrap it - in userinput tags. It will probably be - displayed differently to the user. - - - - - - <sgmltag>informalexample</sgmltag>, - <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and - <sgmltag>userinput</sgmltag> - - Use: - - - - &prompt.user; ls -1 -foo1 -foo2 -foo3 -&prompt.user; ls -1 | grep foo2 -foo2 -&prompt.user; su -Password: -&prompt.root; cat foo2 -This is the file called 'foo2' -]]> - - Appearance: - - - &prompt.user; ls -1 -foo1 -foo2 -foo3 -&prompt.user; ls -1 | grep foo2 -foo2 -&prompt.user; su -Password: -&prompt.root; cat foo2 -This is the file called 'foo2' - - - - - Even though we are displaying the contents of the file - foo2, it is not marked - up as programlisting. Reserve - programlisting for showing fragments of files - outside the context of user actions. - - - - - - In-line elements - - - Emphasising information - - When you want to emphasise a particular word or phrase, use - emphasis. This may be presented as italic, or - bold, or might be spoken differently with a text-to-speech - system. - - There is no way to change the presentation of the emphasis - within your document, no equivalent of HTML's b - and i. If the information you are presenting is - important then consider presenting it in - important rather than - emphasis. - - - <sgmltag>emphasis</sgmltag> - - Use: - - -FreeBSD is without doubt the - premiere Unix like operating system for the Intel architecture.]]> - - Appearance: - - FreeBSD is without doubt the premiere Unix - like operating system for the Intel architecture. - - - - - Applications, commands, options, and cites - - 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. - - In addition, you will occasionally need to list one or more of - the options that a command might take. - - 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. - - Mark up application names with - application. - - When you want to list a command with it's manual section number - (which should be most of the time) the DocBook element is - citerefentry. This will contain a further two - elements, refentrytitle and - manvolnum. The content of - refentrytitle is the name of the command, and the - content of manvolnum is the manual page - section. - - This can be cumbersome to write, and so a series of general entities - have been created to make this easier. Each entity takes the form - &man.manual-page.manual-section;. - - The file that contains these entities is in - doc/share/sgml/man-refs.ent, and can be - referred to using this FPI; - - PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" - - Therefore, the introduction to your documentation will probably - look like this; - - <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -… - -]]> - - Use command when you want to include a - command name “in-line” but present it as something the - user should type in. - - Use option to mark up a command's - options. - - This can be confusing, and sometimes the choice is not always - clear. Hopefully this example makes it clearer. - - - Applications, commands, and options. - - Use: - - -Sendmail is the most - widely used Unix mail application. - -Sendmail includes the - - sendmail - 8 - , &man.sendmail.8;, and &man.newaliases.8; - programs. - -One of the command line parameters to - sendmail - 8 - , , will display the current - status of messages in the mail queue. Check this on the command - line by running sendmail -bp.]]> - - Appearance: - - Sendmail is the most widely used - Unix mail application. - - Sendmail includes the - - sendmail - 8 - , - mailq - 8 - , and - newaliases - 8 - programs. - - One of the command line parameters to - sendmail - 8 - , , will display the current - status of messages in the mail queue. Check this on the command - line by running sendmail -bp. - - - - Notice how the - &man.command.section; notation is easier to follow. - - - - - Files, directories, extensions - - Whenever you wish to refer to the name of a file, a directory, - or a file extension, use filename. - - - <sgmltag>filename</sgmltag> - - Use: - - -The SGML source for the Handbook in English can be - found in /usr/doc/en/handbook/. The first - file is called handbook.sgml in that - directory. You should also see a Makefile - and a number of files with a .ent - extension.]]> - - Appearance: - - The SGML source for the Handbook in English can be found in - /usr/doc/en/handbook/. The first file is - called handbook.sgml in that directory. You - should also see a Makefile and a number of - files with a .ent extension. - - - - - Devices - - - FreeBSD extension - - These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD. - - - When referring to devices you have two choices. You can either - refer to the device as it appears in /dev, or - you can use the name of the device as it appears in the kernel. For - this latter course, use devicename. - - Sometimes you will not have a choice. Some devices, such as - networking cards, do not have entries in /dev, - or the entries are markedly different from those entries. - - - <sgmltag>devicename</sgmltag> - - Use: - - -sio is used for serial - communication in FreeBSD. sio manifests - through a number of entries in /dev, including - /dev/ttyd0 and /dev/cuaa0. - -By contrast, the networking devices, such as - ed0 do not appear in /dev. - -In MS-DOS, the first floppy drive is referred to as - a:. In FreeBSD it is - /dev/fd0.]]> - - Appearance: - - sio is used for serial communication - in FreeBSD. sio manifests through a - number of entries in /dev, including - /dev/ttyd0 and - /dev/cuaa0. - - By contrast, the networking devices, such as - ed0 do not appear in - /dev. - - In MS-DOS, the first floppy drive is referred to as - a:. In FreeBSD it is - /dev/fd0. - - - - - Hosts, domains, IP addresses, and so forth - - - FreeBSD extension - - These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD. - - - You can markup identification information for networked - computers (hosts) in several ways, depending on the nature of the - information. All of them use hostid as the - element, with the role attribute selecting the - type of the marked up information. - - - - No role attribute, or - role="hostname" - - - With no role attribute (i.e., - hostid...hostid the - marked up information is the simple hostname, such as - freefall or wcarchive. - You can explicitly specify this with - role="hostname". - - - - - role="domainname" - - - The text is a domain name, such as - freebsd.org or - ngo.org.uk. There is no hostname - component. - - - - - role="fqdn" - - - The text is a Fully Qualified Domain Name, with both - hostname and domain name parts. - - - - - role="ipaddr" - - - The text is an IP address, probably expressed as a dotted - quad. - - - - - role="netmask" - - - The text is a network mask, which might be expressed as a - dotted quad, a hexadecimal string, or as a - / followed by a number. - - - - - role="mac" - - - The text is an ethernet MAC address, expressed as a series - of 2 digit hexadecimal numbers seperated by colons. - - - - - - <sgmltag>hostid</sgmltag> and roles - - Use: - - -The local machine can always be referred to by the - name localhost, which will have the IP address - 127.0.0.1. - -The freebsd.org domain - contains a number of different hosts, including - freefall.freebsd.org and - bento.freebsd.org. - -When adding an IP alias to an interface (using - ifconfig) always use a - netmask of 255.255.255.255 - (which can also be expressed as 0xffffffff. - -The MAC address uniquely identifies every network card in - in existence. A typical MAC address looks like 08:00:20:87:ef:d0.]]> - - Appearance: - - The local machine can always be referred to by the name - localhost, which will have the IP address 127.0.0.1. - - The freebsd.org domain - contains a number of different hosts, including freefall.freebsd.org and bento.freebsd.org. - - When adding an IP alias to an interface (using - ifconfig) always use a - netmask of 255.255.255.255 (which - can also be expressed as 0xffffffff. - - The MAC address uniquely identifies every network card in - existence. A typical MAC address looks like 08:00:20:87:ef:d0. - - - - - Usernames - - - FreeBSD extension - - These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD. - - - When you need to refer to a specific username, such as - root or bin, use - username. - - - <sgmltag>username</sgmltag> - - Use: - - -To carry out most system administration functions you - will need to be root.]]> - - Appearance: - - To carry out most system administration functions you will - need to be root. - - - - - Describing <filename>Makefile</filename>s - - - FreeBSD extension - - These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD. - - - Two elements exist to describe parts of - Makefiles, maketarget and - makevar. - - maketarget identifies a build target exported - by a Makefile that can be given as a parameter - to make. makevar identifies a - variable that can be set (in the environment, on the - make command line, or within the - Makefile) to influence the process. - - - <sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag> - - Use: - - -Two common targets in a Makefile - are all and clean. - -Typically, invoking all will rebuild the - application, and invoking clean will remove - the temporary files (.o for example) created by - the build process. - -clean may be controlled by a number of - variables, including CLOBBER and - RECURSE.]]> - - Appearance: - - Two common targets in a Makefile are - all and - clean. - - Typically, invoking all will rebuild - the application, and invoking clean will - remove the temporary files (.o for example) - created by the build process. - - clean may be controlled by a number - of variables, including CLOBBER and - RECURSE. - - - - - Literal text - - 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. - - Some of the time, programlisting will be - sufficient to denote this text. programlisting - is not always appropriate, particularly when you want to include a - portion of a file “in-line” with the rest of the - paragraph. - - On these occasions, use literal. - - - <sgmltag>literal</sgmltag> - - Use: - - -The maxusers 10 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.]]> - - Appearance: - - The maxusers 10 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. - - - - - Showing items that the user <emphasis>must</emphasis> fill - in - - 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. - - replaceable is designed for this eventuality. - Use it inside other elements to indicate parts - of that element's content that the user must replace. - - - <sgmltag>replaceable</sgmltag> - - Use: - - - - &prompt.user; man command -]]> - - Appearance: - - - &prompt.user; man command - - - replaceable can be used in many different - elements, including literal. This example also - shows that replaceable should only be wrapped - around the content that the user is meant to - provide. The other content should be left alone. - - Use: - - -The maxusers n - 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. - -For a desktop workstation, 32 is a good value - for n.]]> - - Appearance: - - The maxusers n - 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. - - For a desktop workstation, 32 is a good - value for n. - - - - - - Links - - - Links are also in-line elements. - - - - Linking to other parts of the same document - - 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). - - Each element within DocBook has an attribute called - id. You can place text in this attribute to - uniquely name the element it is attached to. - - This value will be used when you specify the link - source. - - Normally, you will only be linking to chapters or sections, so - you would add the id attribute to these - elements. - - - <literal>id on chapters and sections</literal> - - - - Introduction - - This is the introduction. It contains a subsection, - which is identified as well. - - - Sub-sect 1 - - This is the subsection. - -]]> - - - 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 - id for the subsection is constructed by appending - text to the id of the chapter. This helps to - ensure that they are unique. - - 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 anchor. This element has no content, but - takes an id attribute. - - - <sgmltag>anchor</sgmltag> - - -This paragraph has an embedded - link target in it. It won't show up in - the document.]]> - - - 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 id attribute, you can use either - xref or link. - - Both of these elements have a linkend - attribute. The value of this attribute should be the value that you - have used in a id 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). - - If you use xref then you have no control over - the text of the link. It will be generated for you. - - - Using <sgmltag>xref</sgmltag> - - Assume that this fragment appears somewhere in a document that - includes the id example; - - -More information can be found - in . - -More specific information can be found - in .]]> - - The text of the link will be generated automatically, and will - look like (emphasised text indicates the text - that will be the link); - -
- More information can be found in Chapter - One. - - More specific information can be found in the - section called Sub-sect 1. -
- - - Notice how the text from the link is derived from the section - title or the chapter number. - - - This means that you can not use - xref to link to an id - attribute on an anchor element. The - anchor has no content, so the - xref can not generate the text for the - link. - - - If you want to control the text of the link then use - link. This element wraps content, and the - content will be used for the link. - - - Using <sgmltag>link</sgmltag> - - Assume that this fragment appears somewhere in a document that - includes the id example. - - -More information can be found in - the first chapter. - -More specific information can be found in - FreeBSD - home page instead.]]> - - Appearance: - - Of course, you could stop reading this document and go to the - FreeBSD home page - instead. - - - - - - - * LinuxDoc - - LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the - Linux Documentation - Project, and subsequently adopted by the FreeBSD Documentation - Project. - - 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). - - Both the FreeBSD Documentation Project and the Linux Documentation - Project are migrating from the LinuxDoc DTD to the DocBook DTD. - - The LinuxDoc DTD is available from the ports collection in the - textproc/linuxdoc category. - - - - - - 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 @@ - - - - SGML Primer - - 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. - - Portions of this section were inspired by Mark Galassi's Get Going With DocBook. - - - Overview - - 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. - - 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. - - 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. - - More precisely, they need help identifying what is what. You or I - can look at - -
- To remove /tmp/foo use &man.rm.1;. - - &prompt.user; rm /tmp/foo -
- - 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. - - “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. - - The extra information stored in the markup adds - value 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 increases the - cost of the document. - - The previous example is actually represented in this document like - this; - - To remove /tmp/foo use &man.rm.1;. - -rm /tmp/foo]]> - - As you can see, the markup is clearly separate from the - content. - - 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. - - 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 meta markup - language. - - 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. - - 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 application of SGML. - - A DTD is a complete - 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 - parser 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 validating the document. - - - This processing simply confirms that the choice of elements, their - ordering, and so on, conforms to that listed in the DTD. It does - not check that you have used - appropriate 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). - - - 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. - - - - Elements, tags, and attributes - - 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 content and - elements. - - 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. - - 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. - - 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. - - 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. - - 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 tags. - - A tag is used to identify where a particular element starts, and - where the element ends. The tag is not part of the element - itself. 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. - - For an element called element-name the - start tag will normally look like - <element-name>. The - corresponding closing tag for this element is - </element-name>. - - - Using an element (start and end tags) - - HTML has an element for indicating that the content enclosed by - the element is a paragraph, called p. This - element has both start and end tags. - - -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.

- -

This is another paragraph. But this one is much shorter.

]]> - - - 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. - - - Using an element (start tag only) - - HTML has an element for indicating a horizontal rule, called - hr. This element does not wrap content, so only - has a start tag. - - -This is a paragraph.

- -
- -

This is another paragraph. A horizontal rule separates this - from the previous paragraph.

]]> - - - 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. - - - Elements within elements; <sgmltag>em</sgmltag> - - -This is a simple paragraph where some - of the words have been emphasised.

]]> - - - The DTD will specify the rules detailing which elements can contain - other elements, and exactly what they can contain. - - - People often confuse the terms tags and elements, and use the - terms as if they were interchangeable. They are not. - - 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. - - When this document (or anyone else knowledgable about SGML) refers - to “the <p> tag” they mean the literal text - consisting of the three characters <, - p, and >. But the phrase - “the <p> element” refers to the whole - element. - - This distinction is very subtle. But keep it - in mind. - - - 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. - - An element's attributes are written inside the - start tag for that element, and take the form - attribute-name="attribute-value". - - In sufficiently recent versions of HTML, the p - element has an attribute called align, which suggests - an alignment (justification) for the paragraph to the program displaying - the HTML. - - The align attribute can take one of four defined - values, left, center, - right and justify. If the - attribute is not specified then the default is - left. - - - Using an element with an attribute - - -The inclusion of the align attribute - on this paragraph was superfluous, since the default is left.

- -

This may appear in the center.

]]> - - - Some attributes will only take specific values, such as - left or justify. Others will - allow you to enter anything you want. If you need to include quotes - (") within an attribute then use single quotes around - the attribute value. - - - Single quotes around attributes - - -I'm on the right!

]]> - - - 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 always quote your attribute - values. - - - For you to do… - - 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. - - - - Download and install textproc/docproj - from the FreeBSD ports system. This is a - meta-port that should download and install - all of the programs and supporting files that are used by the - Documentation Project. - - - - Add lines to your shell startup files to set - SGML_CATALOG_FILES. - - - <filename>.profile</filename>, for &man.sh.1; and - &man.bash.1; users - - -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 - - - - <filename>.login</filename>, for &man.csh.1; and - &man.tcsh.1; users - - -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 - - - Then either log out, and log back in again, or run those - commands from the command line to set the variable values. - - - - - - Create example.sgml, and enter the - following text; - - - - - - - An example HTML file - - - -

This is a paragraph containing some text.

- -

This paragraph contains some more text.

- -

This paragraph might be right-justified.

- -]]> - - - - Try and validate this file using an SGML parser. - - Part of textproc/docproj is the - &man.nsgmls.1; validating - parser. 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). - - However, when 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. - - Use &man.nsgmls.1; to check that your document is - valid; - - &prompt.user; nsgmls -s example.sgml - - As you will see, &man.nsgmls.1; returns without displaying any - output. This means that your document validated - successfully. - - - - See what happens when required elements are omitted. Try - removing the title and - /title tags, and re-run the validation. - - &prompt.user; nsgmls -s example.sgml -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 - - The error output from &man.nsgmls.1; is organised into - colon-separated groups, or columns. - - - - - - Column - Meaning - - - - - - 1 - The name of the program generating the error. This - will always be nsgmls. - - - - 2 - The name of the file that contains the error. - - - - 3 - Line number where the error appears. - - - - 4 - Column number where the error appears. - - - - 5 - A one letter code indicating the nature of the - message. I indicates an informational - message, W is for warnings, and - E is for errors - It is not always the fifth column either. - nsgmls -sv displays - nsgmls:I: SP version "1.3" - (depending on the installed version). As you can see, - this is an informational message. - , and X is for - cross-references. As you can see, these messages are - errors. - - - - 6 - The text of the error message. - - - - - - More - information about errors from &man.nsgmls.1; is - available in the Unofficial 'Kindler, - Gentler HTML Validator' FAQ. - - Simply omitting the title tags has - generated 2 different errors. - - 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 head (such as - title). - - The second error is because head elements - must contain a title - 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. - - - - Put the title element back in. - - - - - - - The DOCTYPE declaration - - 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. - - This information is generally expressed on one line, in the DOCTYPE - declaration. - - A typical declaration for a document written to conform with version - 4.0 of the HTML DTD looks like this; - - -]]> - - That line contains a number of different components. - - - - <! - - - Is the indicator that indicates that this - is an SGML declaration. This line is declaring the document type. - - - - - - DOCTYPE - - - Shows that this is an SGML declaration for the document - type. - - - - - html - - - Names the first element that - will appear in the document. - - - - - PUBLIC "-//W3C//DTD HTML 4.0//EN" - - - 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. - - PUBLIC 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 later. - - - - - > - - - Returns to the document. - - - - - - Formal Public Identifiers (FPIs) - - - 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. - - - FPIs must follow a specific syntax. This syntax is as - follows; - - -"Owner//Keyword Description//Language" - - - - Owner - - - This indicates the owner of the FPI. - - If this string starts with “ISO” then this is an - ISO owned FPI. For example, the FPI "ISO - 8879:1986//ENTITIES Greek Symbols//EN" lists - ISO 8879:1986 as being the owner for the set - of entities for greek symbols. ISO 8879:1986 is the ISO number - for the SGML standard. - - Otherwise, this string will either look like - -//Owner or - +//Owner (notice - the only difference is the leading + or - -). - - If the string starts with - then the - owner information is unregistered, with a + - it identifies it as being registered. - - 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). - - Because the FreeBSD Project hasn't been registered the - owner string is -//FreeBSD. And as you can - see, the W3C are not a registered owner either. - - - - - Keyword - - - There are several keywords that indicate the type of - information in the file. Some of the most common keywords are - DTD, ELEMENT, - ENTITIES, and TEXT. - DTD is used only for DTD files, - ELEMENT is usually used for DTD fragments - that contain only entity or element declarations. - TEXT is used for SGML content (text and - tags). - - - - - Description - - - 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. - - - - - Language - - - This is an ISO two-character code that identifies the native - language for the file. EN is used for - English. - - - - - - <filename>catalog</filename> files - - 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. - - In order to do this it can use a catalog file. A catalog file - (typically called catalog) contains lines that - map FPIs to filenames. For example, if the catalog file contained - the line; - - -PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" - - The SGML processor would know to look up the DTD from - strict.dtd in the 4.0 - subdirectory of whichever directory held the - catalog file that contained that line. - - Look at the contents of - /usr/local/share/sgml/html/catalog. This is - the catalog file for the HTML DTDs that will have been installed as - part of the textproc/docproj port. - - - - <envar>SGML_CATALOG_FILES</envar> - - In order to locate a catalog 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. - - In addition, you can set SGML_CATALOG_FILES to - point to the files. This environment variable should consist of a - colon-separated list of catalog files (including their full - path). - - Typically, you will want to include the following files; - - - - /usr/local/share/sgml/docbook/catalog - - - - /usr/local/share/sgml/html/catalog - - - - /usr/local/share/sgml/iso8879/catalog - - - - /usr/local/share/sgml/jade/catalog - - - - You should already have done - this. - - - - - Alternatives to FPIs - - 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. - - The syntax for this is slightly different; - - -]]> - - The SYSTEM 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. - - 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 SYSTEM identifier then everyone - would need to keep their DTDs in the same place. - - - - - Escaping back to SGML - - 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. - - 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. - - These sections are marked by <! ... > in - your document. Everything between these delimiters is SGML syntax as - you might find within a DTD. - - As you may just have realised, the DOCTYPE declaration - is an example of SGML syntax that you need to include in your - document… - - - - Comments - - Comments are an SGML construction, and are normally only valid - inside a DTD. However, as - shows, it is possible to use SGML syntax within your document. - - The delimiters for SGML comments is the string - “--”. The first occurence of this string - opens a comment, and the second closes it. - - - SGML generic comment - - -<!-- test comment --> - - - - - - - -]]> - - - - Use 2 dashes - - There is a problem with producing the Postscript and PDF versions - of this document. The above example probably shows just one hyphen - symbol, - after the <! and - before the >. - - You must use two -, - not one. The Postscript and PDF versions have - translated the two - in the original to a longer, - more professional em-dash, and broken this - example in the process. - - The HTML, plain text, and RTF versions of this document are not - affected. - - ]]> - - If you have used HTML before you may have been shown different rules - for comments. In particular, you may think that the string - <!-- opens a comment, and it is only closed by - -->. - - This is not 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. - - - Errorneous SGML comments - - ]]> - - The SGML parser will treat this as though it were actually; - - -<!THIS IS OUTSIDE THE COMMENT> - - This is not valid SGML, and may give confusing error - messages. - - -]]> - - As the example suggests, do not write - comments like that. - - -]]> - - That is a (slightly) better approach, but it still potentially - confusing to people new to SGML. - - - - For you to do… - - - - Add some comments to example.sgml, and - check that the file still validates using &man.nsgmls.1; - - - - Add some invalid comments to - example.sgml, and see the error messages that - &man.nsgmls.1; gives when it encounters an invalid comment. - - - - - - - Entities - - 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. - - 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. - - There are two types of entities which can be used in two different - situations; general entities and - parameter entities. - - - General Entities - - 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 parameter - entities. - - 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 - &entity-name;. For - example, suppose you had an entity called - current.version which expanded to the current - version number of your product. You could write; - - -The current version of our product is - ¤t.version;.]]> - - When the version number changes you can simply change the - definition of the value of the general entity and reprocess your - document. - - 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. - - Fortunately, you can use the two general entities &lt; and - &amp; whenever you need to include one or other of these - - A general entity can only be defined within an SGML context. - Typically, this is done immediately after the DOCTYPE - declaration. - - - Defining general entities - - - - -]>]]> - - 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. - - The square brackets are necessary to indicate that we are - extending the DTD indicated by the DOCTYPE declaration. - - - - - Parameter entities - - Like general - entities, 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 SGML - context. - - Parameter entities are defined in a similar way to general - entities. However, instead of using - &entity-name; to - refer to them, use - %entity-name; - Parameter entities use the - Percent symbol. - . The definition also includes the % - between the ENTITY keyword and the name of the - entity. - - - Defining parameter entities - - - - - - - -]>]]> - - - This may not seem particularly useful. It will be. - - - - For you to do… - - - - Add a general entity to - example.sgml. - - - -]> - - - - An example HTML file - - - - - -

This is a paragraph containing some text.

- -

This paragraph contains some more text.

- -

This paragraph might be right-justified.

- -

The current version of this document is: &version;

- -]]> - - - - Validate the document using &man.nsgmls.1; - - - - Load example.sgml into your web browser - (you may need to copy it to example.html - before your browser recognises it as an HTML document). - - Unless your browser is very advanced, you won't see the entity - reference &version; replaced with the - version number. Most web browsers have very simplistic parsers - which do not handle proper SGML - This is a shame. Imagine all the problems and hacks (such - as Server Side Includes) that could be avoided if they - did. - . - - - - The solution is to normalise 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. - - You can use &man.sgmlnorm.1; to do this. - - &prompt.user; sgmlnorm example.sgml > example.html - - You should find a normalised (i.e., entity references - expanded) copy of your document in - example.html, ready to load into your web - browser. - - - - 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; - - &prompt.user; sgmlnorm -d example.sgml > example.html - - - - - - - Using entities to include files - - Entities (both general and parameter) are - particularly useful when used to include one file inside another. - - - Using general entities to include files - - Suppose you have some content for an SGML book organised into - files, one file per chapter, called - chapter1.sgml, - chapter2.sgml, and so forth, with a - book.sgml file that will contain these - chapters. - - In order to use the contents of these files as the values for your - entities, you declare them with the SYSTEM keyword. - This directs the SGML parser to use the contents of the named file as - the value of the entity. - - - Using general entities to include files - - - - - - -]> - - - - - &chapter.1; - &chapter.2; - &chapter.3; -]]> - - - - When using general entities to include other files within a - document, the files being included - (chapter1.sgml, - chapter2.sgml, and so on) must - not start with a DOCTYPE declaration. This is a syntax - error. - - - - - Using parameter entities to include files - - 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? - - You can use this to ensure that you can reuse your general - entities. - - 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. - - You could list the entities at the top of each book, but this - quickly becomes cumbersome to manage. - - Instead, place the general entity definitions inside one file, - and use a parameter entity to include that file within your - document. - - - Using parameter entities to include files - - First, place your entity definitions in a separate file, called - chapters.ent. This file contains the - following; - - - - -]]> - - 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; - - - - - - -%chapters; -]> - - - &chapter.1; - &chapter.2; - &chapter.3; -]]> - - - - - For you to do… - - - Use general entities to include files - - - - Create three files, para1.sgml, - para2.sgml, and - para3.sgml. - - Put content similar to the following in each file; - - -This is the first paragraph.

]]> - - - - Edit example.sgml so that it looks like - this; - - - - - - -]> - - - - An example HTML file - - - -

The current version of this document is: &version;

- - ¶1; - ¶2; - ¶3; - -]]> - - - - Produce example.html by normalising - example.sgml. - - &prompt.user; sgmlnorm -d example.sgml > example.html - - - - Load example.html in to your web - browser, and confirm that the - paran.sgml files - have been included in example.html. - - - - - - Use parameter entities to include files - - - You must have taken the previous steps first. - - - - - Edit example.sgml so that it looks like - this; - - - %entities; -]> - - - - An example HTML file - - - -

The current version of this document is: &version;

- - ¶1; - ¶2; - ¶3; - -]]> - - - - Create a new file, entities.sgml, with - this content; - - - - - -]]> - - - - Produce example.html by normalising - example.sgml. - - &prompt.user; sgmlnorm -d example.sgml > example.html - - - - Load example.html in to your web - browser, and confirm that the - paran.sgml files - have been included in example.html. - - - - - - - - Marked sections - - SGML provides a mechanism to indicate that particular pieces of the - document should be processed in a special way. These are termed - “marked sections”. - - - Structure of a marked section - - -<![ KEYWORD [ - Contents of marked section -]]> - - - As you would expect, being an SGML construct, a marked section - starts <!. - - The first square bracket begins to delimit the marked - section. - - KEYWORD describes how this marked - section should be processed by the parser. - - The second square bracket indicates that the content of the marked - section starts here. - - The marked section is finished by closing the two square brackets, - and then returning to the document context from the SGML context with - > - - - Marked section keywords - - - <literal>CDATA</literal>, <literal>RCDATA</literal> - - These keywords denote the marked sections content - model, and allow you to change it from the - default. - - When an SGML parser is processing a document, it keeps track - of what is called the “content model”. - - 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. - - The two content models you will probably find most useful are - CDATA and RCDATA. - - CDATA 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. - - RCDATA is for “Entity references and - character data” If the parser is in this content model then it - is expecting to see characters and entities. - < loses its special status, but & will still be treated as - starting the beginning of a general entity. - - 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. - - - - - Using a CDATA marked section - - -<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 [ 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.

- -
    -
  • This is a listitem
    • -
  • This is a second listitem
    • -
  • This is a third listitem
    • -
- -

This is the end of the example.

]]> - ]]> -</programlisting> - - If you look at the source for this document you will see this - technique used throughout. - - - - - <literal>INCLUDE</literal> and - <literal>IGNORE</literal> - - If the keyword is INCLUDE then the contents - of the marked section will be processed. If the keyword is - IGNORE then the marked section is ignored and - will not be processed. It will not appear in the output. - - - Using <literal>INCLUDE</literal> and - <literal>IGNORE</literal> in marked sections - - -<![ INCLUDE [ - This text will be processed and included. -]]> - -<![ IGNORE [ - This text will not be processed or included. -]]> - - - 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. - - It becomes more useful when you realise you can use parameter entities - to control this. Remember that parameter entities can only be used - in SGML contexts, and the keyword of a marked section - is an SGML context. - - 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. - - Create a parameter entity, and set it's value to - INCLUDE. 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. - - When you want to produce the hard-copy version of the document, - change the parameter entity's value to IGNORE and - reprocess the document. - - - Using a parameter entity to control a marked - section - - -<!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. -]]> - - When producing the hard-copy version, change the entity's - definition to; - - -<!ENTITY % electronic.copy "IGNORE"> - - On reprocessing the document, the marked sections that use - %electronic.copy as their keyword will be - ignored. - - - - - - For you to do… - - - - Create a new file, section.sgml, that - contains the following; - - -<!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> - ]]> - - <![ [ - <p>This paragraph might appear in the output, or it - might not.</p> - - <p>Its appearance is controlled by the - parameter entity.</p> - ]]> - </body> -</html> - - - - 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. - - - - Change the definition of the text.output - entity from INCLUDE to - IGNORE. Re-normalise the file, and examine the - output to see what has changed. - - - - - - - Conclusion - - 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. - - - - 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 @@ - - - - * Stylesheets - - 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. - - For DocBook, we are using stylesheets written in DSSSL. For HTML we - are using CSS. - - - * DSSSL - - The Documentation Project uses a slightly customised version of - Norm Walsh's modular DocBook stylesheets. - - These can be found in - textproc/dsssl-docbook-modular. - - - - * CSS - - - - - - 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 @@ - - - - * The FAQ - - - - - - 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 @@ - - - - * The Handbook - - - Logical structure - - The Handbook is written to comply with the FreeBSD DocBook extended - DTD. - - The Handbook is organised as a DocBook book. It - is then divided into parts, each of which may contain - several chapters. chapters are - further subdivided into sections (sect1) and - subsections (sect2, sect3) and so - on. - - - - Physical organisation - - The Handbook (and its translations) are in the - doc/language/handbook - subdirectory of the main CVS - repository. language corresponds to the ISO - language code for that translation, en for English, - ja for Japanese, and so on. - - There are a number of files and directories within the - handbook directory. - - - 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, doc@FreeBSD.ORG. - - - - <filename>Makefile</filename> - - The Makefile 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). - - A more detailed description of the Makefile - is in . - - - - <filename>handbook.sgml</filename> - - This is the top level document in the Handbook. It contains the - Handbook's DOCTYPE - declaration, as well as the elements that describe the - Handbook's structure. - - handbook.sgml uses parameter entities - to load in the files with the .ent extension. - These files (described later) then define general entities that - are used throughout the rest of the Handbook. - - - - <filename><replaceable>directory</replaceable>/chapter.sgml</filename> - - Each chapter in the Handbook is stored in a file called - chapter.sgml in a separate directory from the - other chapters. Each directory is named after the value of the - id attribute on the chapter - element. - - For example, if one of the chapter files contains: - - -... -]]> - - then it will be called chapter.sgml in the - kernelconfiguration directory. In general, the - entire contents of the chapter will be held in this file. - - When the HTML version of the Handbook is produced, this will yield - kernelconfiguration.html. This is because of the - id value, and is not related to the name of the - directory. - - In earlier versions of the Handbook the files were stored in the - same directory as handbook.sgml, and named after - the value of the id attribute on the file's - chapter 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. - - A brief look will show that there are many directories with - individual chapter.sgml files, including - basics/chapter.sgml, - introduction/chapter.sgml, and - printing/chapter.sgml. - - - 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). - - - Each chapter.sgml file will not be a complete - SGML document. In particular, they will not have their own DOCTYPE - line at the start of the file. - - This is unfortunate for two reasons; - - - - 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 - would force you to rebuild the Handbook every - time you want to see the effect a change as had on just one - chapter. - - - - Emacs' sgml-mode can not use it to - determine the DTD to use, losing useful benefits of - sgml-mode (element completion, automatic - validation, and so on). - - - - - - - Style guide - - To keep the source for the Handbook consistent when many different - people are editing it, please follow these style conventions. - - - Letter case - - Tags are entered in lower case, <para>, - not <PARA>. - - Text that appears in SGML contexts is generally written in upper - case, <!ENTITY…>, and - <!DOCTYPE…>, not - <!entity…> and - <!doctype…>. - - - - Indentation - - Each file starts with indentation set at column 0, - regardless of the indentation level of the file - which might contain this one. - - 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. - - For example, the source for this section looks something - like; - - - - ... - - - ... - - - Indentation - - Each file starts with indentation set at column 0, - regardless of the indentation level of the file - which might contain this one. - - 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. - - ... - - -]]> - - If you use Emacs or - Xemacs to edit the files then - sgml-mode should be loaded automatically, and the - Emacs local variables at the bottom of each file should enforce these - styles. - - - - White space changes - - When committing changes, do not commit changes to the - content at the same time as changes to the - formatting. - - 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. - - 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. - - - - - Converting the Handbook to other formats - - - - - - - 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 @@ - - - - * The Website - - - - - - 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 @@ - - - - Tools - - 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. - - All these tools are available as FreeBSD Ports and Packages, - greatly simplifying the work you have to do to install - them. - - 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. - - - Use <filename>textproc/docproj</filename> if possible - - You can save yourself a lot of time if you install the - textproc/docproj port. This is a - meta-port which does not contain any software - itself. Instead, it depends on various other ports being installed - correctly. Installing this port should - automatically download and install all of the packages listed in this - chapter that you need that are missing from your system. - - 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. - - 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; - - &prompt.root; make JADETEX=yes install - - or - - &prompt.root; make JADETEX=no install - - as necessary. - - - - Mandatory tools - - - Software - - These programs are required before you can usefully work with - the FreeBSD documentation. They are all included in - textproc/docproj. - - - - SP - (textproc/sp) - - - A suite of applications, including a validating SGML parser, - and an SGML normaliser. - - - - - Jade - (textproc/jade) - - - A DSSSL implementation. Used for converting marked up - documents to other formats, including HTML and TeX. - - - - - Tidy - (www/tidy) - - - An HTML 'pretty printer', used to reformat some of the - automatically generated HTML so that it is easier to - follow. - - - - - Lynx - (www/lynx-current) - - - A text-mode WWW browser, &man.lynx.1; can also convert - HTML files to plain text. - - - - - - - DTDs and Entities - - 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. - - - - HTML DTD (textproc/html) - - - HTML is the markup language of choice for the World Wide - Web, and is used throughout the FreeBSD web site. - - - - - LinuxDoc DTD (textproc/linuxdoc) - - - Some FreeBSD documentation is marked up in LinuxDoc. The - FDP is actively migrating from LinuxDoc to DocBook. - - - - - DocBook DTD (textproc/docbook) - - - 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. - - - - - ISO 8879 entities - (textproc/iso8879) - - - 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. - - - - - - - Stylesheets - - The stylesheets are used when converting and formatting the - documentation for display on screen, printing, and so on. - - - - Modular DocBook Stylesheets - (textproc/dsssl-docbook-modular) - - - The Modular DocBook Stylesheets are used when converting - documentation marked up in DocBook to other formats, such as - HTML, or RTF. - - - - - - - - Optional tools - - 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. - - - Software - - - - JadeTeX and - teTeX - (print/jadetex and - print/teTeX-beta) - - - Jade and - teTeX are used to convert DocBook - documents to DVI, Postscript, and PDF formats. The - JadeTeX macros are needed in order to - do this. - - 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 - JadeTeX and - teTeX. This can be a significant - space and time saver, as teTeX is - over 30MB in size. - - - If you decide to install - JadeTeX and - teTeX then you will need to - configure teTeX after - JadeTeX has been installed. - print/jadetex/pkg/MESSAGE contains - detailed instructions explaining what you need to do. - - - - - - Emacs or - xemacs - (editors/emacs or - editors/xemacs) - - - 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. - - 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. - - - - - If anyone has recommendations for other software that is useful - when manipulating SGML documents, please let Nik Clayton - (nik@freebsd.org) know, so they can be added to this - list. - - - - - 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 @@ - - - - Translations - - This is the FAQ for people translating the FreeBSD documentation - (FAQ, Handbook, tutorials, man pages, and others) to different - languages. - - It is very heavily based on the translation FAQ - from the FreeBSD German Documentation Project, originally written by Frank - Grnder elwood@mc5sys.in-berlin.de and translated back to - English by Bernd Warken bwarken@mayn.de. - - The FAQ maintainer is Nik Clayton - nik@FreeBSD.org. - - - - - Why a FAQ? - - - - 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. - - - - - - What do i18n and l10n - mean? - - - - i18n means - internationalisation and l10n - means localisation. They are just a convenient - shorthand. - - i18n can be read as “i” followed by - 18 letters, followed by “n”. Similarly, - l10n is “l” followed by 10 letters, - followed by “n”. - - - - - - Is there a mailing list for translators? - - - - Yes, freebsd-translate@ngo.org.uk. Subscribe by - sending a message to - freebsd-translate-request@ngo.org.uk with the word - subscribe in the body of the message. - - You will receive a reply asking you to confirm your subscription - (in exactly the same manner as the the FreeBSD lists at FreeBSD.org). - - 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. - - The mailing list is archived, but they are not currently - searchable. Sending the message help to - majordomo@ngo.org.uk will send back instructions on - how to access the archive. - - It is expected that the mailing list will transfer to FreeBSD.org and therefore become - official in the near future. - - - - - - Are more translators needed? - - - - 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. - - You do not have to be a professional translator to be able to - help. - - - - - - What languages do I need to know? - - - - 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. - - English is not strictly necessary. For example, you could do a - Hungarian translation of the FAQ from the Spanish - translation. - - - - - - What software do I need to know? - - - - It is strongly recommended that you maintain a local copy of the - FreeBSD CVS repository (at least the documentation part) either - using CTM or - CVSup. The "Staying current with FreeBSD" - chapter in the Handbook explains how to use these - applications. - - You should be comfortable using CVS. - This will allow you to see what has changed between different - versions of the files that make up the documentation. - - [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] - - - - - - How do I find out who else might be translating to the same - language? - - - - The Documentation - Project translations page 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. - - If no one is listed on that page as translating for your - language then send a message to - freebsd-doc@freebsd.org in case someone else is - thinking of doing a translation, but hasn't announced it yet. - - - - - - No one else is translating to my language. What do I do? - - - - Congratulations, you have just started the “FreeBSD - your-language-here Documentation - Translation Project”. Welcome aboard. - - 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. - - 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. - - You should subscribe to the - freebsd-translate@ngo.org.uk mailing list (as - described earlier). - - 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. - - Then pick a document and start translating. It is best to start - with something fairly small—either the FAQ, or one of the - tutorials. - - - - - - I've translated some documentation, where do I send it? - - - - 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. - - 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). - - - - - - I'm the only person working on translating to this language, how - do I submit my translation? - - or - - We're a translation team, and want to submit documentation that - our members have translated for us? - - - - First, make sure your translation is organised properly. This - means that it should drop in to the existing documentation tree and - build straight away. - - Currently, the FreeBSD documentation is stored in a top level - directory called doc/. Directories below this - are named according to the language code they are written in, as - defined in ISO639 (/usr/share/misc/iso639 on a - version of FreeBSD newer than 20th January 1999). - - 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. - - Finally, you should have directories for each document. - - For example, a hypothetical Swedish translation might look - like - - doc/ - sv/ - Makefile - FAQ/ - Makefile - *.sgml - - sv 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 - This directory structure is going to change radically quite - soon. Please see the on-going discussions on the - doc@FreeBSD.org mailing list for more - information. - . - - Use &man.tar.1; and &man.gzip.1; to compress up your - documentation, and send it to the project. - - &prompt.user; cd doc -&prompt.user; tar cf swedish-docs.tar sv -&prompt.user; gzip -9 swedish-docs.tar - - Put swedish-docs.tar.gz 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 - nik@FreeBSD.org, and arrange to e-mail the files - when it is convenient. - - 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. - - Someone (probably the Documentation Project Manager, currently - Nik Clayton nik@FreeBSD.org) will then take your - translation and confirm that it builds. In particular, the - following things will be looked at: - - - - Do all your files use RCS strings (such as "ID"). - - - - Does make all in the - sv directory work correctly. - - - - Does make install work correctly. - - - - If there are any problems then whoever is looking at the - submission will get back to you to try and work them out. - - If there are no problems then your translation will be committed - as soon as possible. - - - - - - Can I include language or country specific text in my - translation? - - - - We would prefer that you did not. - - For example, suppose that you are translating the Handbook to - Korean, and want to include a section about retailers in Korea in - your Handbook. - - 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. - - 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. - - Thanks. - - - - - - How should language specific characters be included? - - Non-ASCII characters in the documentation should be included - using SGML entities. - - Briefly, these look like an ampersand (&), the name of the - entity, and a semi-colon (;). - - The entity names are defined in ISO8879, which is in the ports - tree as textproc/iso8879. - - A few examples include - - - - &eacute; - é - Small “e” with an acute accent - - - - &Eacute; - É - Large “E” with an acute accent - - - - &uuml; - ü - Small “u” with an umlaut - - - - After you have installed the iso8879 port, the files in - /usr/local/share/sgml/iso8879 contain the - complete list. - - - - - - Addressing the reader - - - - In the English documents, the reader is addressed as - “you”, there is no formal/informal distinction as there - is in some languages. - - 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. - - - - - - Do I need to include any additional information in my - translations? - - - - Yes. - - The header of the English version of each document will look - something like this; - - ]]> - - The exact boilerplate may change, but it will always include an - Id line and the phrase The FreeBSD Documentation - Project. - - Your translated documents should include their own Id line, and change the - FreeBSD Documentation Project line to - The FreeBSD language - Documentation Project. - - In addition, you should add a third line which indicates which - revision of the English text this is based on. - - So, the Spanish version of this file might start - - ]]> - - - - - - 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 @@ - - - - Writing style - - In order to promote consistency between the myriad authors of the - FreeBSD documentation, some guidelines have been drawn up for authors to - follow. - - - - Do not use contractions - - - Do not use contractions. Always spell the phrase out in full. - “Don't use contractions” would be wrong. - - Avoiding contractions makes for a more formal tone, is more - precise, and slightly easier for translators. - - - - - Use the serial comma - - - 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”. - - For example, look at the following quote; - -
- This is a list of one, two and three items. -
- - Is this a list of three items, “one”, - “two”, and “three”, or a list of two items, - “one” and “two and three”? - - It is better to be explicit and include a serial comma; - -
- This is a list of one, two, and three items. -
- - - - - Avoid redundant phrases - - - Try not to use redundant phrases. In particular, “the - command”, “the file”, and “man - command” are probably redundant. - - These two examples show this for commands. The second example - is preferred. - - - Use the command cvsup to update your - sources - - - - Use cvsup to update your sources - - - These two examples show this for filenames. The second example - is preferred. - - - … in the filename - /etc/rc.local… - - - - … in - /etc/rc.local… - - - These two examples show this for manual references. The second - example is preferred (the second example uses - citerefentry). - - - See man csh for more - information. - - - - See &man.csh.1; - - - - - - For more information about writing style, see Elements of - Style, by William Strunk. - - - - 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 @@ - - - - - - - - - - -Fonts and FreeBSD -A Tutorial - - - -Dave -Bodenstab - -
imdave@synet.net
- - - - -Wed Aug 7, 1996 - -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. - - - - - -Introduction - -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. - - - - -Basic terminology - -There are many different font formats and associated font file -suffixes. A few that will be addressed here are: - - -.pfa, .pfb - -Postscript type 1 fonts. The .pfa is the -Ascii form and .pfb the -Binary form. - - - -.afm - -The font metrics associated with a type 1 -font. - - - -.pfm - -The printer font metrics associated with a type 1 -font. - - - -.ttf - -A TrueType font - - - -.fot - -An indirect reference to a TrueType font (not an -actual font) - - - -.fon, .fnt - -Bitmapped screen fonts - - - - -The .fot file is used by Windows as sort -of a symbolic link to the actual TrueType font -(.ttf) file. The .fon font -files are also used by Windows. I know of no way to use this font -format with FreeBSD. - - - - -What font formats can I use? - -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: - - - -Driver - - - -syscons - -.fnt - - - - - - - - - -Application - - - - -Ghostscript - -.pfa, .pfb, .ttf - - - - -X11 - - -.pfa, .pfb - - - - -Groff - - -.pfa, .afm - - - - -Povray - - -.ttf - - - - - - - - - - - -The .fnt 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 .fnt -files used by syscons under FreeBSD may not be the same format as a -.fnt file one encounters in the MSDOS/Windows -environment. I have not made any attempt at using other -.fnt files other than those provided with -FreeBSD. - - - - -Setting a virtual console to 80x60 line mode - -First, a 8x8 font must be loaded. -/etc/sysconfig should contain the lines: - -# Choose font 8x8 from /usr/share/syscons/fonts/* (or NO for default) -font8x8=/usr/share/syscons/fonts/cp437-8x8.fnt - - - -The command to actually switch the mode is -vidcontrol1: - -bash$ vidcontrol VGA_80x60 - - - -Various screen orientated programs, such as -vi1, must be able to -determine the current screen dimensions. These can be set with -stty1: - -bash$ stty crt rows 60 columns 80 - - - -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: - - - -Modify /etc/sysconfig as above - - - -Add to /etc/rc.local: - -for tty in /dev/ttyv? -do - vidcontrol VGA_80x60 <$tty >/dev/null 2>&1 -done - - - - -Add to /etc/profile: - -TTYNAME=`basename \`tty\`` -if expr "$TTYNAME" : 'ttyv' >/dev/null -then - stty crt rows 60 columns 80 -fi - - - - - - - -References: -stty1, -vidcontrol1. - - - - -Using type 1 fonts with X11 - -X11 can use either the .pfa or the -.pfb format fonts. The X11 fonts are located in -various subdirectories under -/usr/X11R6/lib/X11/fonts. Each font file is -cross referenced to its X11 name by the contents of the -fonts.dir file in each directory. - -There is already a directory named 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: - -Create a directory to contain the font files -bash$ mkdir -p /usr/local/share/fonts/type1 -bash$ cd /usr/local/share/fonts/type1 - -Place the .pfa, .pfb and .afm files here -One might want to keep readme files, and other documentation -for the fonts here also -bash$ cp /cdrom/fonts/atm/showboat/showboat.pfb . -bash$ cp /cdrom/fonts/atm/showboat/showboat.afm . - -Maintain an index to cross reference the fonts -bash$ echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX - - - -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: - --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 - - - -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 -strings1 on the font -file. For example: - -bash$ 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-- - - -Using this information, a possible name might be: - --type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 - - - -The components of our name are: - - -Foundry - -Lets just name all the new fonts type1. - - - -Family - -The name of the font. - - - -Weight - -Normal, bold, medium, semibold, etc. From the -strings1 output -above, it appears that this font has a weight of -medium. - - - -Slant - -roman, italic, oblique, -etc. Since the ItalicAngle is zero, -roman will be used. - - - -Width - -Normal, wide, condensed, extended, etc. Until it can be examined, -the assumption will be normal. - - - -Additional style - -Usually omitted, but this will indicate that -the font contains decorative capital letters. - - - -Spacing - -proportional or monospaced. Proportional -is used since isFixedPitch is false. - - - - - - -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 - -…-normal-r-normal-…-p-… - -as the name, and then use -xfontsel1 to examine it -and adjust the name based on the appearance of the font. - -So, to complete our example: - -Make the font accessible to X11 -bash$ cd /usr/X11R6/lib/X11/fonts/Type1 -bash$ ln -s /usr/local/share/fonts/type1/showboat.pfb . - -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$ 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 - -fonts.scale seems to be identical to fonts.dir… -bash$ cp fonts.dir fonts.scale - -Tell X11 that things have changed -bash$ xset fp rehash - -Examine the new font -bash$ xfontsel -pattern -type1-* - - - -References: -xfontsel1, -xset1, -The X Windows System in a Nutshell, O'Reilly & Associates. - - - - -Using type 1 fonts with Ghostscript - -Ghostscript references a font via its Fontmap -file. This must be modified in a similar way to the X11 -fonts.dir file. Ghostscript can use either the -.pfa or the .pfb format -fonts. Using the font from the previous example, here is how to use -it with Ghostscript: - -Put the font in Ghostscript's font directory -bash$ cd /usr/local/share/ghostscript/fonts -bash$ ln -s /usr/local/share/fonts/type1/showboat.pfb . - -Edit Fontmap so Ghostscript knows about the font -bash$ cd /usr/local/share/ghostscript/4.01 -bash$ ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq - -Use Ghostscript to examine the font -bash$ 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>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>quit - - - -References: fonts.txt in the Ghostscript -4.01 distribution - - - - -Using type 1 fonts with Groff - -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 ps device. A font file must be -created for each font that groff can use. A groff font name is just -a file in /usr/share/groff_font/devps. With our -example, the font file could be -/usr/share/groff_font/devps/SHOWBOAT. The file -must be created using tools provided by groff. - -The first tool is 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: - -bash$ cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp -bash$ ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq - - - -This tool will create the groff font file from the metrics file -(.afm suffix.) Continuing with our -example: - -Many .afm files are in Mac format&hellip ^M delimited lines -We need to convert them to unix style ^J delimited lines -bash$ cd /tmp -bash$ cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm - -Now create the groff font file -bash$ cd /usr/share/groff_font/devps -bash$ /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT - - - -The font can now be referenced with the name SHOWBOAT. - -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 pfbtops tool -is used to create the .pfa format of the font, -and the download file is modified to reference the new -font. The download file must reference the internal -name of the font. This can easily be determined from the groff font -file as illustrated: - -Create the .pfa font file -bash$ pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa - -Of course, if the .pfa file is already -available, just use a symbolic link to reference it. - -Get the internal font name -bash$ fgrep internalname SHOWBOAT -internalname Showboat - -Tell groff that the font must be down loaded -bash$ ex download -:$a -Showboat showboat.pfa -. -:wq - - - -To test the font: - -bash$ cd /tmp -bash$ 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$ groff -Tps example.t >example.ps - -To use ghostscript/ghostview -bash$ ghostview example.ps - -To print it -bash$ lpr -Ppostscript example.ps - - - -References: -/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man, -groff_font5, -groff_char5, -pfbtops1. - - - - - Converting TrueType fonts to a groff/postscript format for - groff - - 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: - - - - ttf2pf - - - TrueType to postscript convertsion utilities. This - allows conversion of a TrueType font to an ascii font - metric (.afm) file. - - Currently available at http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf. - Note: These files are postscript programs and must be - downloaded to disk by holding down the - Shift key when clicking on the - link. Otherwise, your browser may try to launch - ghostview to view them. - - The files of interest are: - - - - GS_TTF.PS - - - PF2AFM.PS - - - - ttf2pf.ps - - - - The funny upper/lower case is due to their being - intended also for DOS shells. - ttf2pf.ps makes use of the others as - upper case, so any renaming must be consistent with - this. (Actually, GS_TTF.PS and - PFS2AFM.PS 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 - /usr/local/share/groff_font/devps(?). - - - - - afmtodit - - - Creates font files for use with groff from ascii font - metrics file. This usually resides in the directory, - /usr/src/contrib/groff/afmtodit, and - requires some work to get going. - - - If you're paranoid about working in the - /usr/src tree, simply copy the - contents of the above directory to a work - location. - - - In the work area, you'll need to make the - utility. Just type: - - -# make -f Makefile.sub afmtodit - - - You may also need to copy - /usr/contrib/groff/devps/generate/textmap - to - /usr/share/groff_font/devps/generate - if it doesn't already exist. - - - - - Once all these utilities are in place, you're ready to - commence: - - - - Create the .afm file by - typing: - - -% gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name - - - Where, TTF_name is your - TrueType font file, PS_font_name - is the file name for the .pfa file, - AFM_name is the name you wish for - the .afm file. If you do not specify - output file names for the .pfa or - .afm files, then default names will be - generated from the TrueType font file name. - - This also produces a .pfa file, the - ascii postscript font metrics file - (.pfb is for the binrary form). This - won't be needed, but could (I think) be useful for a - fontserver. - - For example, to convert the 30f9 Barcode font using the - default file names, use the following command: - - -% gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf -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. - - - If you want the converted fonts to be stored in - A.pfa and B.afm, - then use this command: - - -% gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B -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. - - - - - Create the groff postscript file: - - Change directories to - /usr/share/groff_font/devps 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 DESC, - text.enc and - generate/textmap as being in this - directory.) - - -% afmtodit -d DESC -e text.enc file.afm \ - generate/textmap PS_font_name - - - Where, file.afm is the - AFM_name created by - ttf2pf.ps above, and - PS_font_name is the font name - used from that command, as well as the name that - groff1 - will use for references to this font. For example, assuming - you used the first tiff2pf.ps command - above, then the 3of9 Barcode font can be created using the - command: - - -% afmtodit -d DESC -e text.enc 3of9.afm \ - generate/textmap 3of9 - - - Ensure that the resulting - PS_font_name file (e.g., - 3of9 in the example above) is located - in the directory - /usr/share/groff_font/devps by copying - or moving it there. - - Note that if ttf2pf.ps 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 - .afm file prior to running - afmtodit. This name must also match the - one used in the Fontmap file if you wish to pipe - groff1 into - gs1. - - - - - -Can TrueType fonts be used with other programs? - -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. - -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 :-). - -This rather dismal situation may soon change. -The FreeType Project -is currently developing a useful set of FreeType tools: - - -The xfsft 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 Juliusz -Chroboczek's page for further information. Porting instructions -for FreeBSD can be found at Stephen Montgomery's -software page. - - - -xfstt is another font -server for X11, available under -ftp://sunsite.unc.edu/pub/Linux/X11/fonts. - - -A program called ttf2bdf can produce -BDF files suitable for use in an X environment from TrueType files. Linux -binaries are said to be available from ftp://crl.nmsu.edu/CLR/multiling/General/. - - - - -For people requiring the use of Asian TrueType fonts, the -XTT font server may be worth a look. Information about -XTT can be found at URL: http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html. - - - -and others … - - - - -The -FreeType Projects page - is a good starting point for information on these and other -free TrueType projects. - - - - -Where can additional fonts be obtained? - -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: - - -ftp://ftp.winsite.com (Formerly -CICA) - -http://www.simtel.net/simcgi-bin/dosfind.cgi - -ftp://ftp.coast.net/ - -http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html - -http://www.esselte.com/letraset/index.html - -http://www.inil.com/users/elfring/esf.htm - - - - - - -Additional questions - - - - - -What use are the .pfm files? - - - -Can one generate the .afm file from a .pfa or .pfb? - - - -How to generate the groff character mapping files for postscript fonts -with non-standard character names? - - - -Can xditview and devX?? devices be setup to access all the new fonts? - - - -It would be good to have examples of using TrueType fonts with povray and -ghostscript. - - - - - - - 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 @@ - - - - %includes; -]> - - - -&header; - -

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 - freebsd-doc@FreeBSD.org.

- - - - -&footer; - - - 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 @@ - - - - - - - - -An MH Primer - - - -Matt -Midboe - -
-matt@garply.com -
- - - -v1.0, 16 January 1996 - -This document contains an introduction to using MH on -FreeBSD - - - - - -Introduction - -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 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. - -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 - to the command to have it display the options -for that command. - -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: - -# pkg_add /cdrom/packages/mh-6.8.3.tgz - -You will notice that it created a /usr/local/lib/mh -directory for you as well as adding several binaries to the -/usr/local/bin directory. If you would prefer to compile -it yourself then you can anonymous ftp it from ftp.ics.uci.edu or louie.udel.edu. - -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 comp.mail.mh newsgroup. Also you can -read the FAQ -for MH. The best resource for MH is the O'Reilly and Associates book -written by Jerry Peek. - - - - -Reading Mail - -This section covers how to use inc, -show, scan, next, -prev, rmm, rmf, and -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 inc this doesn't really make any sense but with -commands like show it is useful to know. - -A message list can consist of something like 23 20 -16 which will act on messages 23, 20 and 16. This is fairly simple -but you can do more useful things like 23-30 which will -act on all the messages between 23 and 30. You can also specify -something like cur:10 which will act on the current -message and the next 9 messages. The cur, -last, and first messages are special -messages that refer to the current, last or first message in the -folder. - - - -<command>inc</>, <command>msgchk</>—read in your new email or check it - -If you just type in inc and hit return -you will be well on your way to getting started with MH. The first -time you run 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: - - 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 - -This is the same thing you will see from a scan (see -). If you just run inc with no -arguments it will look on your computer for email that is supposed to -be coming to you. - -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 inc a few command -line arguments. - -tempest% inc -host mail.pop.org -user username -norpop - -That tells inc to go to mail.pop.org to -download your email, and that your username on their system is -username. The option tells -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. - -The msgchk command is used to get information on -whether or not you have new email. msgchk takes the same - and options that -inc takes. - - - - -<command>show</>, <command>next</> and <command>prev</>—displaying and moving through email - -show is to show a letter in your current folder. -Like inc, show is a fairly straightforward -command. If you just type show and hit return -then it displays the current message. You can also give specific -message numbers to show: - -tempest% show 32 45 56 - -This would display message numbers 32, 45 and 56 right after each -other. Unless you change the default behavior show -basically just does a more on the email message. - -next is used to move onto the next message and -prev will go to the previous message. Both commands have -an implied show command so that when you go to the next -message it automatically displays it. - - - - -<command>scan</>—shows you a scan of your messages - -scan will display a brief listing of the messages -in your current folder. This is an example of what the -scan command will give you. - - 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 - -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 -+ means that message is the current message, so if you do -a show it will display that message. - -One useful option for scan is the -option. This will list your messages with the highest message number -first and lowest message number last. Another useful option with -scan is to have it read from a file. If you want to scan -your incoming mailbox on FreeBSD without having to inc it -you can do scan -file -/var/mail/username. This can be used with -any file that is in the mbox format. - - - - -<command>rmm</> and <command>rmf</>—remove the current message or folder - -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 removed -messages. - -The 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. - - - - -A typical session of reading with MH - -The first thing that you will want to do is inc -your new mail. So at a shell prompt just type in inc and -hit return. - -tempest% 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% - -This shows you the new email that has been added to your mailbox. So -the next thing to do is show the email and move around. - -tempest% 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% rmm -tempest% 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). - - -The rmm removed the current message and the -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: - -tempest% 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% - -Then if I wanted to read message number 27 I would do a -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. - - - - - - -Folders and Mail Searching - -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 inc for the first time and it asked -you if it could create a Mail directory it began storing -everything in that directory. If you look at that directory you will -find a directory named inbox. The inbox -directory houses all of your incoming mail that hasn't been thrown -anywhere else. - -Whenever you create a new folder a new directory is going to be -created underneath your MH 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 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. - -Just as you can use message lists like 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 scan +freebsd it -will scan your freebsd folder, and your current folder -will be changed to freebsd. If you do a show -+freebsd 23 16 42, show is going to switch to your -freebsd folder and display messages 23, 16 and 42. So -remember that - - - -<command>pick</>—search email that matches certain criteria - -pick is one of the more complex commands in the MH -system. So you might want to read the -pick1 man page for a -more thorough understanding. At its simplest level you can do -something like - -tempest% pick -search pci -15 -42 -55 -56 -57 - - -This will tell pick to look through every single line in -every message in your current folder and tell you which message -numbers it found the word pci in. You can then -show those messages and read them if you wish or -rmm them. You would have to specify something like -show 15 42 55-57 to display them though. A slightly more -useful thing to do is this: - -tempest% pick -search pci -seq pick -5 hits -tempest% show pick - -This will show you the same messages you just didn't have to work as -hard to do it. The option is really an -abbreviation of and 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 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. - -Doing a pick -search can be a bit more time -consuming than just searching for message from someone, or to -someone. So pick allows you to use the following -predefined search criteria: - - - - - - -search based upon who the message is to - - - - - - -search based on who is in the cc list - - - - - - -search for who sent the message - - - - - - -search for emails with this subject - - - - - - -find emails with a matching dat - - - - - - -search for any other component in the header. (i.e. - - - - - - -This allows you to do things like - -tempest% pick -to freebsd-hackers@freebsd.org -seq hackers - -to get a list of all the email send to the FreeBSD hackers mailing -list. pick also allows you to group these criteria in -different ways using the following options: - - - -… … - - - -… &hellip - - - - … - - - - … - - - -These commands allow you to do things like - -tempest% pick -to freebsd-hackers -and -cc freebsd-hackers - -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 - -tempest% pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci - - -Basically this says pick (to freebsd-hackers and not cc'd on -freebsd-questions) and the subject is pci. 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 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. - - - - -<command>folder</>, <command>folders</>, <command>refile</>—three useful programs for folder maintenance - -There are three programs which are primarily just for -manipulating your folders. The folder program is used to -switch between folders, pack them, and list them. At its simplest -level you can do a folder +newfolder and -you will be switched into newfolder. From there on -out all your MH commands like comp, repl, -scan, and show will act on that -newfolder folder. - -Sometimes when you are reading and deleting messages you will -develop holes in your folders. If you do a scan -you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do -a folder -pack 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 rmm'd messages. - -If you need statistics on your folders you can do a -folders or folder -all 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 -folder +foldername. A folders command looks -like this: - - 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. - - - -The refile command is what you use to move messages -between folders. When you do something like refile 23 -+netfuture message number 23 is moved into the -netfuture folder. You could also do something like -refile 23 +netfuture/latest which would put message -number 23 in a subfolder called latest under the -netfuture folder. If you want to keep a message in the -current folder and link it you can do a refile -link 23 -+netfuture which would keep 23 in your current -inbox but also list in your netfuture -folder. You are probably beginning to realize some of the really -powerful things you can do with MH. - - - - - -Sending Mail - -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 whatnow program. When -you are at the What now? prompt you can tell it to -send, list, edit, -edit, push, and 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 whatnow program what to do with your -email. - - - -<command>comp</>, <command>forw</>, <command>reply</>—compose, forward or reply to a message to someone - -The comp program has a few useful command line -options. The most important one to know right now is the - option. When MH is installed the default -editor is usually a program called 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 comp -editor /usr/bin/vi/ or comp --editor /usr/local/bin/pico/ instead. Once you have run -comp you are in your editor and you see -something that looks like this: - -To: -cc: -Subject: --------- - - - -You need to put the person you are sending the mail to after the -To: line. It works the same way for the other headers -also, so you would need to put your subject after the -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. - -To:freebsd-rave@freebsd.org -cc: -Subject:And on the 8th day God created the FreeBSD core team --------- -Wow this is an amazing operating system. Thanks! - -You can now save this message and exit your editor. You will see the -What now? prompt and you can type in -send or s and hit -return. Then the freebsd core team will receive their just -rewards. As I mentioned earlier you can also use other commands, for -example quit if you don't want to send the -message. - -The 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 forw it -will forward your current message. You can always tell it to forward -something else by doing something like forw 23 and then -message number 23 will be put in your outgoing message instead of the -current message. Beyond those small differences forw -functions exactly the same as comp. You go through the -exact same message sending process. - -The repl command will reply to whatever your -current message is, unless you give it a different message to reply -to. repl will do its best to go ahead and fill in some of -the email headers already. So you will notice that the -To: header already has the address of the recipient in -there. Also the 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. You can use all, -to, cc, me after the - option to have 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. - - - - -<filename>components</>, and <filename>replcomps</>—components files for <command>comp</> and <command>repl</> - -The components file is usually in -/usr/local/lib/mh. 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 -comp command just copies this -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 components file: - -To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.freebsd.org/ -------- - - -MH would then copy this components file and throw you into your -editor. The components file is fairly simple. If you -wanted to have a signature on those messages you would just put your -signature in that components file. - -The replcomps file is a bit more complex. The default -replcomps looks like this: - -%(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%>\ --------- - - - -It's in the same basic format as the components file but -it contains quite a few extra formatting codes. The -%(lit) command makes room for the address. The -%(formataddr is a function that returns a proper email -address. The next part is %< which means if and -the {reply-to} means the reply-to field in the original -message. So that might be translated this way: - -%<if {reply-to} the original message has a reply-to -then give that to formataddr, %? else {from} take the -from address, %? else {sender} take the sender address, %? -else {return-path} take the return-path from the original -message, %> endif. - - -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 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. - - - - 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 @@ - - - - - - -Installing and Using FreeBSD With Other Operating Systems - - - -Jay -Richmond - -
-jayrich@sysc.com -
- - - - -6 August 1996 - -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 -andrsn@stanford.edu, Randall Hopper -rhh@ct.picker.com, and Jordan K. Hubbard -jkh@time.cdrom.com - - - - - -Overview - -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 section may be of the most use -to you. It contains descriptions of specific working computer setups -that use multiple operating systems. - -This document assumes that you have already made room on your -hard disk for an additional operating system. Any time you -repartition your hard drive, you run the risk of destroying the data -on the original partitions. However, if your hard drive is completely -occupied by DOS, you might find the FIPS utility (included on the -FreeBSD CD-ROM in the \TOOLS directory or via -ftp) -useful. It lets you repartition your hard disk without destroying the -data already on it. There is also a commercial program available -called Partition Magic, which lets you size and delete partitions -without consequence. - - - - -Overview of Boot Managers - -These are just brief descriptions of some of the different boot -managers you may encounter. Depending on your computer setup, you may -find it useful to use more than one of them on the same -system. - - - - -Boot Easy - - -This is the default boot manager used with FreeBSD. It has the -ability to boot most anything, including BSD, OS/2 (HPFS), Windows 95 -(FAT and FAT32), and Linux. Partitions are selected with the -function keys. - - - - -OS/2 Boot Manager - - -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 Linux HOWTOs -on the World Wide Web for more information on booting Linux with -OS/2's boot manager. - - - - -OS-BS - - This is an alternative to Boot Easy. It gives you -more control over the booting process, with the ability to set the -default partition to boot and the booting timeout. The beta version -of this programs allows you to boot by selecting the OS with your -arrow keys. It is included on the FreeBSD CD in the -\TOOLS directory, and via ftp. - - - -LILO, or LInux LOader - - -This is a limited boot manager. Will boot FreeBSD, though some -customization work is required in the LILO configuration file. - - - - - -About FAT32FAT32 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. - - - - -A Typical Installation - -Let's say I have two large EIDE hard drives, and I want to -install FreeBSD, Linux, and Windows 95 on them. - -Here's how I might do it using these hard disks: - - - -/dev/wd0 (first physical hard disk) - - - -/dev/wd1 (second hard disk) - - - - - -Both disks have 1416 cylinders. - - - -I boot from a MS-DOS or Windows 95 boot disk that -contains the 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. - -I reboot and install Windows 95 (easier said than done) -on the C: partition. - -The next thing I do is install Linux. I'm not sure about -all the distributions of Linux, but slackware includes LILO (see -). When I am partitioning out my hard disk with -Linux fdisk, I would put all of Linux on the first -drive (maybe 300 megs for a nice root partition and some swap -space). - -After I install Linux, and are prompted about installing -LILO, make SURE that I install it on the boot sector of my root -Linux partition, not in the MBR (master boot record). - -The remaining hard disk space can go to FreeBSD. I also -make sure that my FreeBSD root slice does not go beyond the 1024th -cylinder. (The 1024th cylinder is 528 megs into the disk with our -hypothetical 720MB disks). I will use the rest of the hard drive -(about 270 megs) for the /usr and / slices -if I wish. The rest of the second hard disk (size depends on the -amount of my Windows application/data partition that I created in -step 1 can go to the /usr/src slice and swap -space. - -When viewed with the Windows 95 fdisk utility, my hard drives -should now look something like this: - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - -** May say FAT16 or FAT32 if you are using the OEM SR2 update. -See ). - -Install FreeBSD. I make sure to boot with my first hard -disk set at NORMAL in the BIOS. If it is not, I'll have -the enter my true disk geometry at boot time (to get this, boot -Windows 95 and consult Microsoft Diagnostics (MSD.EXE), -or check your BIOS) with the parameter hd0=1416,16,63 -where 1416 is the number of cylinders on my hard -disk, 16 is the number of heads per track, and -63 is the number of sectors per track on the -drive. - -When partitioning out the hard disk, I make sure to install -Boot Easy on the first disk. I don't worry about the second disk, -nothing is booting off of it. - -When I reboot, Boot Easy should recognize my three -bootable partitions as DOS (Windows 95), Linux, and BSD -(FreeBSD). - - - - - - -Special Considerations - -Most operating systems are very picky about where and how they are -placed on the hard disk. Windows 95 and DOS need to be on the first -primary 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. - -If you install Windows 95 on an existing BSD system, it will -destroy the MBR, and you will have to reinstall your -previous boot manager. Boot Easy can be reinstalled by using the -BOOTINST.EXE utility included in the \TOOLS directory on the CD-ROM, -and via ftp. You can -also re-start the installation process and go to the partition -editor. From there, mark the FreeBSD partition as bootable, -select Boot Manager, and then type W to (W)rite out the information -to the MBR. You can now reboot, and Boot Easy should then -recognize Windows 95 as DOS. - -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 ) 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. - - - - -Examples - -(section needs work, please send your example to -jayrich@sysc.com). - -FreeBSD+Win95: If you installed FreeBSD after Windows 95, you -should see DOS on the Boot Easy menu. This is Windows -95. If you installed Windows 95 after FreeBSD, read above. As long as your hard disk does not have 1024 -cylinders you should not have a problem booting. If one of your -partitions goes beyond the 1024th cylinder however, and you get -messages like invalid system disk under DOS (Windows 95) -and FreeBSD will not boot, try looking for a setting in your BIOS -called > 1024 cylinder support or NORMAL/LBA -mode. DOS may need LBA (Logical Block Addressing) in order to boot -correctly. If the idea of switching BIOS settings every time you -boot up doesn't appeal to you, you can boot FreeBSD through DOS via -the FBSDBOOT.EXE utility on the CD (It should find your -FreeBSD partition and boot it.) - -FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger -can boot all of these operating systems, so that shouldn't be a -problem. - -FreeBSD+Linux: You can also use Boot Easy to boot both operating -systems. - -FreeBSD+Linux+Win95: (see ) - - - - -Other Sources of Help - -There are many Linux HOW-TOs that -deal with multiple operating systems on the same hard disk. - -The Linux+DOS+Win95+OS2 -mini-HOWTO offers help on configuring the OS/2 boot manager, and the -Linux+FreeBSD -mini-HOWTO might be interesting as well. The Linux-HOWTO is -also helpful. - -The NT Loader -Hacking Guide provides good information on multibooting -Windows NT, '95, and DOS with other operating systems. - -And Hale Landis's "How It Works" document pack contains some good info -on all sorts of disk geometry and booting related topics. Here are a few -links that might help you find it: ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip, -http://www.cs.yorku.ca/People/frank/docs/. - -Finally, don't overlook FreeBSD's kernel documentation on the booting -procedure, available in the kernel source distribution (it unpacks to -file:/usr/src/sys/i386/boot/biosboot/README.386BSD. - - - - -Technical Details - -(Contributed by Randall Hopper, -rhh@ct.picker.com) - -This section attempts to give you enough basic information -about your hard disks and the disk booting process so that you can -troubleshoot most problems you might encounter when getting set up to -boot several operating systems. It starts in pretty basic terms, so -you may want to skim down in this section until it begins to look -unfamiliar and then start reading. - - - -Disk Primer - -Three fundamental terms are used to describe the location of -data on your hard disk: Cylinders, Heads, and Sectors. It'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. - -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: (# of cylinders) × (# -heads) × (63 sectors/track) × (512 -bytes/sect) For example, on my 1.6 Gig Western -Digital AC31600 EIDE hard disk,that's: (3148 -cyl) × (16 heads) × (63 sectors/track) × (512 -bytes/sect) - -which is 1,624,670,208 bytes, or around 1.6 Gig. - -You can find out the physical disk geometry (number of -cylinders, heads, and sectors/track counts) for your hard disks using -ATAID or other programs off the net. Your hard disk probably came -with this information as well. Be careful though: if you're using -BIOS LBA (see ), you can't use just any -program to get the physical geometry. This is because many programs -(e.g. MSD.EXE or FreeBSD fdisk) don't identify the -physical disk geometry; they instead report the -translated geometry (virtual numbers from using LBA). -Stay tuned for what that means. - -One other useful thing about these terms. Given 3 -numbers—a cylinder number, a head number, and a -sector-within-track number—you identify a specific absolute -sector (a 512 byte block of data) on your disk. Cylinders and Heads -are numbered up from 0, and Sectors are numbered up from 1. - -For those that are interested in more technical details, -information on disk geometry, boot sectors, BIOSes, etc. can be found -all over the net. Query Lycos, Yahoo, etc. for boot -sector or master boot record. Among the useful info -you'll find are Hale Landis's How It Works document -pack. See the section for a few pointers to -this pack. - -Ok, enough terminology. We're talking about booting -here. - - - - -The Booting Process - -On the first sector of your disk (Cyl 0, Head 0, Sector 1) -lives the Master Boot Record (MBR). It contains a map of your disk. -It identifies up to 4 partitions, each of which is a -contiguous chunk of that disk. FreeBSD calls partitions -slices to avoid confusion with it's own partitions, but -we won't do that here. Each partition can contain its own operating -system. - -Each partition entry in the MBR has a Partition -ID, a Start Cylinder/Head/Sector, and an -End Cylinder/Head/Sector. The Partition ID tells what -type of partition it is (what OS) and the Start/End tells where it -is. lists a smattering of some common -Partition IDs. - - -Partition IDs</> -<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 - -Now the interesting stuff that you need to watch out for. - - -The dreaded 1024 cylinder limit and how BIOS LBA helps - -The first part of the booting process is all done through the -BIOS, (if that'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. - -The BIOS interface used to read the hard disk during this period -(INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 -bits to the Head Number, and 6 bits to the Sector Number. This -restricts users of this interface (i.e. boot managers hooked into -your disk's MBR as well as OS loaders hooked into the Boot Sectors) -to the following limits: - -1024 cylinders, max -256 heads , max -64 sectors/track, max (actually 63, 0 isn't -available) - - - -Now big hard disks have lots of cylinders but not a lot of -heads, so invariably with big hard disks the number of cylinders is -greater than 1024. Given this and the BIOS interface as is, you -can'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: - -1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) -× 512 bytes/sector - - - -which is around the often-mentioned 528MB limit. - -This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA -gives the user of the BIOS API calls access to physical cylinders above -1024 though the BIOS interfaces by redefining a cylinder. That is, it -remaps your cylinders and heads, making it appear through the BIOS as -though the disk has fewer cylinders and more heads than it actually -does. In other words, it takes advantage of the fact that hard disks have -relatively few heads and lots of cylinders by shifting the balance between -number of cylinders and number of heads so that both numbers lie below the -above-mentioned limits (1024 cylinders, 256 heads). - -With BIOS LBA, the hard disk size limitation is virtually -removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA -BIOS, you can put FreeBSD or any OS anywhere you want and not hit the -1024 cylinder limit. - -To use my 1.6 Gig Western Digital as an example again, it's -physical geometry is: - -(3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector) - - - -However, my BIOS LBA remaps this to: - -( 787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector) - - - -giving the same effective size disk, but with cylinder and head -counts within the BIOS API's range (Incidentally, I have both Linux and -FreeBSD existing on one of my hard disks above the 1024th physical -cylinder, and both operating systems boot fine, thanks to BIOS LBA). - - - - -Boot Managers and Disk Allocation - -Another gotcha to watch out when installing boot managers is -allocating space for your boot manager. It's best to be aware of -this issue up front to save yourself from having to reinstall one or -more of your OSs. - -If you followed the discussion in -about the Master Boot Sector (where the MBR is), Partition Boot -Sectors, and the booting process, you may have been wondering just -exactly where on your hard disk that nifty boot manager is going to -live. Well, some boot managers are small enough to fit entirely -within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along -with the partition table. Others need a bit more room and actually -extend a few sectors past the Master Boot Sector in the Cylinder 0 -Head 0 track, since that's typically free…typically. - -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. - -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. - -For reference, the following boot managers use the -Master Boot Sector to store their code and data: - - - -OS-BS 1.35 - - - -Boot Easy - - - -LILO - - - - - -These boot managers use a few additional sectors after the -Master Boot Sector: - - - -OS-BS 2.0 Beta 8 (sectors 2-5) - - - -OS/2's boot manager - - - - - - - - -What if your machine won't boot? - -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. - -If you have a bootable DOS partition on your disk, you can boot -off a DOS floppy, and run: - -A:\> FDISK /MBR - - - -to put the original, simple DOS boot code back into the system. You can -then boot DOS (and DOS only) off the hard drive. Alternatively, just -re-run your boot manager installation program off a bootable floppy. - - - - - diff --git a/en/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 @@ - - - - - - - - -For People New to Both FreeBSD and Unix - - - -Annelise -Anderson - -
andrsn@andrsn.stanford.edu
- - - - -August 15, 1997 - -Congratulations on installing FreeBSD! This -introduction is for people new to both FreeBSD -and 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. - - - - - -Logging in and Getting Out - -Log in (when you see login:) as a user you created during -installation or as root. (Your FreeBSD -installation will already have an account for root; root can go -anywhere and do anything, including deleting essential files, so be -careful!) The symbols % and # in the following stand for the prompt -(yours may be different), with % indicating an ordinary user and -# indicating root. - -To log out (and get a new login: prompt) type - -# exit - -as often as necessary. Yes, press enter after -commands, and remember that Unix is -case-sensitive—exit, not -EXIT. - -To shut down the machine type: - -# /sbin/shutdown -h now - -Or to reboot type - -# /sbin/shutdown -r now - -or - -# /sbin/reboot - - - -You can also reboot with -CtrlAltDelete. -Give it a little time to do its work. This is equivalent to -/sbin/reboot in recent releases of FreeBSD, and is -much, much better than hitting the reset button. You don't want to -have to reinstall this thing, do you? - - - - -Adding A User with Root Privileges - -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 - -# adduser - -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 /etc/adduser.conf, -an editable file. - -Suppose you create a user jack with -full name Jack Benimble. Give jack a password -if security (even kids around who might pound on the keyboard) is an -issue. When it asks you if you want to invite jack into other -groups, type wheel - -Login group is ``jack''. Invite jack into other groups: wheel - -This will make it possible to log in as jack and -use the su command to become root. Then you won't -get scolded any more for logging in as root. - -You can quit adduser any time by typing -CtrlC, and at -the end you'll have a chance to approve your new user or simply type -n for no. You might want to create a -second new user (jill?) so that when you edit jack's login files, -you'll have a hot spare in case something goes wrong. - -Once you've done this, use exit -to get back to a login prompt and log in as -jack. 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. - -If you already created a user and you want the user to be able -to su to root, you can log in as root -and edit the file /etc/group, adding jack to the -first line (the group wheel). But first you need to practice -vi, the text editor--or use the simpler text -editor, ee, installed on recent version of -FreeBSD. - -To delete a user, use the rmuser command. - - - - -Looking Around - -Logged in as an ordinary user, look around and try out some -commands that will access the sources of help and information within -FreeBSD. - -Here are some commands and what they do: - -id - -Tells you who you are! - - - - -pwd - - -Shows you where you are—the current -working directory. - - - - -ls - - -Lists the files in the current directory. - - - - -ls - - -Lists the files in the current directory with a -* after executables, a / after -directories, and an @ after symbolic links. - - - - -ls - - -Lists the files in long format—size, -date, permissions. - - - - -ls - - -Lists hidden dot -files with the others. If you're root, thedot files -show up without the switch. - - - - -cd - - -Changes directories. cd -.. backs up one level; note the -space after cd. cd -/usr/local goes there. cd -~ goes to the home directory of the -person logged in—e.g., /usr/home/jack. -Try cd /cdrom, and then -ls, to find out if your CDROM is mounted and -working. - - - - -view filename - - -Lets you look at a file (named -filename without changing it. Try -view /etc/fstab. -:q to quit. - - - - -cat filename - - - -Displays filename on screen. If -it's too long and you can see only the end of it, press -ScrollLock and use the up-arrow to -move backward; you can use ScrollLock with man pages -too. Press ScrollLock again to quit scrolling. You -might want to try cat on some of the dot files in -your home directory—cat -.cshrc, cat -.login, cat -.profile. - - - - - -You'll notice aliases in .cshrc for some of the -ls commands (they're very convenient). -You can create other aliases by editing .cshrc. -You can make these aliases available to all users on the system by -putting them in the system-wide csh configuration file, -/etc/csh.cshrc. - - - - -Getting Help and Information - -Here are some useful sources of help. -Text stands for something of your choice -that you type in—usually a command or filename. - - -apropos text - - -Everything containing string text -in the whatis database. - - - -man text - - -The man page for text. The major -source of documentation for Un*x systems. man -ls will tell you all the ways to use -the ls command. Press Enter to -move through text, -Ctrlb to go -back a page, Ctrlf to -go forward, q or -Ctrlc to -quit. - - - -which text - - -Tells you where in the user's path the command -text is found. - - - -locate text - - -All the paths where the string text -is found. - - - -whatis text - - -Tells you what the command text -does and its man page. Typing whatis * will tell -you about all the binaries in the current directory. - - - -whereis text - - -Finds the file text, giving its full -path. - - - - -You might want to try using whatis on some -common useful commands like cat, -more, grep, -mv, find, -tar, chmod, -chown, date, and -script. more lets you read a -page at a time as it does in DOS, e.g., ls -l | -more or more -filename. The -* works as a wildcard—e.g., ls -w* will show you files beginning with -w. - -Are some of these not working very well? Both -locate and whatis -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. - -# /etc/daily -output omitted -# /etc/weekly -output omitted -# /etc/monthly -output omitted - - -If you get tired waiting, press -AltF2 to get -another virtual console, 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 clear at the prompt -to clear the screen. Once they've run, you might want to look at -/var/mail/root and -/var/log/messages. - -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 UNIX System -Administration Handbook (Prentice-Hall, 1995, ISBN -0-13-15051-7)—the second edition with the red cover; or -Æleen Frisch's Essential System -Administration (O'Reilly & Associates, 1993, ISBN -0-937175-80-3). I used Nemeth. - - - - -Editing Text - -To configure your system, you need to edit text files. Most of -them will be in the /etc directory; and you'll -need to su to root to be able to change them. You -can use the easy ee, but in the long run the -text editor vi is worth learning. There's an -excellent tutorial on vi in -/usr/src/contrib/nvi/docs/tutorial if you have -that installed; otherwise you can get it by ftp to -ftp.cdrom.com in the directory -FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial. - -Before you edit a -file, you should probably back it up. Suppose you want to edit -/etc/rc.conf. You could just use cd -/etc to get to the /etc directory and -do: - -# cp rc.conf rc.conf.orig - - -This would copy rc.conf to -rc.conf.orig, and you could later copy -rc.conf.orig to rc.conf to recover the original. But even -better would be moving (renaming) and then copying back: - -# mv rc.conf rc.conf.orig -# cp rc.conf.orig rc.conf - - -because the mv command preserves the original date -and owner of the file. You can now edit -rc.conf. If you want the original back, you'd -then mv rc.conf rc.conf.myedit -(assuming you want to preserve your edited version) and then - -# mv rc.conf.orig rc.conf - -to put things back the way they were. - -To edit a file, type - -# vi filename - -Move through the text with the arrow keys. Esc (the -escape key) puts vi in command mode. Here are some -commands: - -x - -delete letter the cursor is on - - - - -dd - - -delete the entire line (even if it wraps on the screen) - - - - -i - - -insert text at the cursor - - - - -a - - -insert text after the cursor - - - - -Once you type i or a, you can enter text. -Esc puts you back in command mode where you can type - -:w - -to write your changes to disk and continue editing - - - - -:wq - - -to write and quit - - - - -:q! - - -to quit without saving changes - - - - -/text - - -to move the cursor to text; -/Enter (the enter key) to find -the next instance of text. - - - - -G - - -to go to the end of the file - - - - -nG - - -to go to line n in -the file, where n is a number - - - - -CtrlL - - -to redraw the screen - - - - -Ctrlb and Ctrlf - - -go back -and forward a screen, as they -do with more and view. - - - - - - -Practice with vi in your home directory by creating -a new file with vi filename and adding -and deleting text, saving the file, and calling it up again. -vi delivers some surprises because it's really quite -complex, and sometimes you'll inadvertently issue a command that will -do something you don't expect. (Some people actually like -vi—it's more powerful than DOS EDIT—find out -about the :r command.) Use 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 :w, and -use :q! to get out and start over (from -your last :w) when you need to. - -Now you can cd to /etc, -su to root, use vi to edit the file -/etc/group, and add a user to wheel so the user -has root privileges. Just add a comma and the user's login name to -the end of the first line in the file, press Esc, and use -:wq to write the file to disk and quit. Instantly -effective. (You didn't put a space after the comma, did you?) - - - - -Printing Files from DOS - -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 - -# man chmod | col -b > chmod.txt - -will remove formatting codes and send the man page to -the chmod.txt file -instead of showing it on your screen. Now put a dos-formatted -diskette in your floppy drive a, su to -root, and type - -# /sbin/mount -t msdos /dev/fd0 /mnt - -to mount the floppy drive on /mnt. - -Now (you no longer need to be root, and you can type -exit to get back to being user jack) you can go to the -directory where you created chmod.txt and copy the file to the floppy -with: - -% cp chmod.txt /mnt - -and use ls /mnt to get a directory listing of -/mnt, which should show the file -chmod.txt. - -You might especially want to make a file from -/sbin/dmesg by typing - -% /sbin/dmesg > dmesg.txt - -and copying dmesg.txt to the floppy. -/sbin/dmesg 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 -freebsd-questions@FreeBSD.ORG or on a USENET -group—like FreeBSD isn't finding my tape drive, what do -I do?—people will want to know what dmesg -has to say. - -You can now dismount the floppy drive (as root) to get the disk -out with - -# /sbin/umount /mnt - -and reboot to go to DOS. Copy these files to a DOS directory, call -them up with DOS EDIT, Windows Notepad or 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 print command. (Copying files from -FreeBSD to a mounted dos partition is in some cases still a little -risky.) - -Getting the printer printing from FreeBSD involves creating an -appropriate entry in /etc/printcap and creating -a matching spool directory in -/var/spool/output. If your printer is on -lpt0 (what dos calls LPT1), you may only -need to go to /var/spool/output and (as root) -create the directory lpd by typing: - -mkdir lpd, if it 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 FreeBSD -handbook. - - - - -Other Useful Commands - - - -df - -shows file space and mounted systems. - - - - -ps aux - - -shows processes running. ps ax is a narrower form. - - - - -rm filename - - -remove filename. - - - - -rm -R dir - - -removes a directory dir and all -subdirectories—careful! - - - - -ls -R - - -lists files in the current -directory and all subdirectories; -I used a variant, ls -AFR > where.txt, -to get a list of all -the files in / and (separately) -/usr before I found better -ways to find files. - - - - -passwd - - -to change user's password (or root's password) - - - - -man hier - - -man page on the Unix file system - - - - - -Use find to locate filename in /usr -or any of its subdirectories with - -% find /usr -name "filename" - -You can use * as a wildcard in -"filename" (which should be in -quotes). If you tell find to search in / -instead of /usr it will look for the file(s) on -all mounted file systems, including the CDROM and the dos -partition. - -An excellent book that explains Unix commands and utilities is -Abrahams & Larson, Unix for the Impatient -(2nd ed., Addison-Wesley, 1996). There's also a lot of Unix -information on the Internet. Try the Unix Reference -Desk. - - - - -Next Steps - -You should now have the tools you need to get around and edit -files, so you can get everything up and running. There is a great -deal of information in the FreeBSD handbook (which is probably on -your hard drive) and FreeBSD's -web site. A wide variety of packages and ports are on the -Walnut Creek CDROM as well -as the web site. The handbook tells you more about how to use them -(get the package if it exists, with pkg_add -/cdrom/packages/All/packagename, -where packagename is the filename of the -package). The cdrom has lists of the packages and ports with brief -descriptions in cdrom/packages/index, -cdrom/packages/index.txt, and -cdrom/ports/index, with fuller descriptions in -/cdrom/ports/*/*/pkg/DESCR, where the -*s represent subdirectories of kinds of programs -and program names respectively. - -If you find the handbook too sophisticated (what with -lndir and all) on installing ports from the cdrom, -here's what usually works: - -Find the port you want, say kermit. There will be -a directory for it on the cdrom. Copy the subdirectory to -/usr/local (a good place for software you add -that should be available to all users) with: - -# cp -R /cdrom/ports/comm/kermit /usr/local - - -This should result in a /usr/local/kermit -subdirectory that has all the files that the -kermit subdirectory on the CDROM has. - -Next, create the directory /usr/ports/distfiles -if it doesn't already exist using mkdir. Now check -check /cdrom/ports/distfiles for a -file with a name that indicates it's the port you want. Copy that -file to /usr/ports/distfiles; in recent versions -you can skip this step, as FreeBSD will do it for you. -In the case of kermit, there is no -distfile. - -Then cd to the subdirectory of -/usr/local/kermit that has the file -Makefile. Type - -# make all install - - - -During this process the port will ftp to get any compressed -files it needs that it didn't find on the cdrom or in -/usr/ports/distfiles. If you don't have your -network running yet and there was no file for the port in -/cdrom/ports/distfiles, you will have to get -the distfile using another machine and copy it to -/usr/ports/distfiles from a floppy or your dos -partition. Read Makefile (with cat or -more or view) to find out where to go (the -master distribution site) to get the file and what its name is. Its -name will be truncated when downloaded to DOS, and after you get it -into /usr/ports/distfiles you'll have to rename -it (with the mv command) to its original name so it can -be found. (Use binary file transfers!) Then go back to -/usr/local/kermit, find the directory with -Makefile, and type make all install. - -The other thing that happens when installing ports or packages -is that some other program is needed. If the installation stops with -a message can't find unzip or whatever, you -might need to install the package or port for unzip before you -continue. - -Once it's installed type rehash to make FreeBSD -reread the files in the path so it knows what's there. (If you get a -lot of path not found messages when you use -whereis or which, you might want to make additions to the -list of directories in the path statement in -.cshrc in your home directory. The path -statement in Unix does the same kind of 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 ./ before the command to make it -work; no space after the slash.) - -You might want to get the most recent version of Netscape from -their ftp site. (Netscape -requires the X Window System.) There's now a FreeBSD version, so look -around carefully. Just use gunzip -filename and tar xvf -filename on it, move the binary to -/usr/local/bin or some other place binaries are -kept, rehash, and then put the following lines in -.cshrc in each user's home directory or (easier) -in /etc/csh.cshrc, the system-wide csh start-up -file: - -setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls - -This assumes that the file XKeysymDB and the directory -nls are in /usr/X11R6/lib/X11; if -they're not, find them and put them there. - -If you originally got Netscape as a port using the CDROM (or -ftp), don't replace /usr/local/bin/netscape 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 -netscape.bin and replace the old binary, which -is /usr/local/lib/netscape/netscape.bin. - - - - - -Your Working Environment - -Your shell is the most important part of your working environment. -In DOS, the usual shell is command.com. The shell is what interprets -the commands you type on the command line, and thus communicates with -the rest of the operating system. You can also write shell -scripts, which are like DOS batch files: a series of commands to be -run without your intervention. - -Two shells come installed with FreeBSD: csh and sh. csh is good for -command-line work, but scripts should be written with sh (or bash). You can -find out what shell you have by typing echo $SHELL. - -The csh shell is okay, but tcsh does everything csh does and more. It -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 cd -. It's also much -easier to alter your prompt with tcsh. It makes life a lot easier. - -Here are the three steps for installing a new shell: - - 1. Install the shell as a port or a package, just as you -would any other port or package. Use rehash and -which tcsh (assuming you're installing tcsh) to -make sure it got installed. - - 2. As root, edit /etc/shells, adding -a line in the file for the new shell, in this case /usr/local/bin/tcsh, -and save the file. (Some ports may do this for you.) - - 3. Use the chsh command to change your shell to -tcsh permanently, or type tcsh at the prompt to -change your shell without logging in again. - -Note: It can be dangerous to change root's shell -to something other than sh or csh on early versions of FreeBSD and many -other versions of Unix; you may not have a working shell when the system -puts you into single user mode. The solution is to use su -m -to become root, which will give you the tcsh as root, because the shell is part -of the environment. You can make this permanent by adding it to your -.tcshrc file as an alias with alias su su -m. - -When tcsh starts up, it will read the -/etc/csh.cshrc and /etc/csh.login -files, as does csh. It will also read the -.login file in your home directory and the -.cshrc -file as well, unless you provide a .tcshrc -file. This you can do by simply copying .cshrc -to .tcshrc. - -Now that you'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 .tcshrc that will tell you how many -commands you have typed, what time it is, and what directory you are in. -It also produces a > if you're an ordinary user and -a # if you're root, but tsch will do that in any -case: - - set prompt = "%h %t %~ %# " - -This should go in the same place as the existing set prompt line -if there is one, or under "if($?prompt) then" if not. -Comment out the old line; you can always switch back to it if you prefer -it. Don't forget the spaces and quotes. You can get the .tcshrc reread by typing source .tcshrc. - -You can get a listing of other environmental variables that -have been set by typing env at the prompt. The -result will show you your default editor, pager, and terminal type, -among possibly many others. A useful command if you log in from a -remote location and can't run a program because the terminal isn't -capable is -setenv TERM vt100. - - - - -Other - -As root, you can dismount the CDROM with /sbin/umount -/cdrom, take it out of the drive, insert another one, and mount it -with /sbin/mount_cd9660 /dev/cd0a /cdrom assuming -cd0a is the device name for your CDROM drive. The -most recent versions of FreeBSD let you mount the cdrom with just -/sbin/mount /cdrom. - -Using the live 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 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 /cdrom file system -instead of in /usr and its subdirectories, which -is where they're expected to be. Read man lndir. - - - - -Comments Welcome - -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. - -Annelise Anderson, andrsn@andrsn.stanford.edu - - - 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 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 @@ - - - -
- -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> -