diff options
Diffstat (limited to 'en_US.ISO_8859-1/tutorials')
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/Makefile | 13 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/Makefile.inc | 4 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/ddwg/Makefile | 6 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml | 1142 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/disklessx/Makefile | 5 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/doc.ftr | 5 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/doc.hdr | 14 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/index.sgml | 49 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/ppp/Makefile | 6 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/tutorials/ppp/ppp.sgml | 1739 |
10 files changed, 0 insertions, 2983 deletions
diff --git a/en_US.ISO_8859-1/tutorials/Makefile b/en_US.ISO_8859-1/tutorials/Makefile deleted file mode 100644 index d89b4c97ac..0000000000 --- a/en_US.ISO_8859-1/tutorials/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -# $Id: Makefile,v 1.12 1998-01-18 22:27:43 jfieber Exp $ - -DOCS?= index.sgml -SUBDIR= devel diskformat disklessx fonts mh multios newuser upgrade -DOCSUBDIR= ddwg ppp -SGMLOPTS+= -links -hdr ${.CURDIR}/doc.hdr -ftr ${.CURDIR}/doc.ftr - - -.if defined $(NEW_BUILD) -SUBDIR= -.endif - -.include "../web.mk" diff --git a/en_US.ISO_8859-1/tutorials/Makefile.inc b/en_US.ISO_8859-1/tutorials/Makefile.inc deleted file mode 100644 index 7da7fe75c2..0000000000 --- a/en_US.ISO_8859-1/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_US.ISO_8859-1/tutorials/ddwg/Makefile b/en_US.ISO_8859-1/tutorials/ddwg/Makefile deleted file mode 100644 index f28e8dcab7..0000000000 --- a/en_US.ISO_8859-1/tutorials/ddwg/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.3 1997-07-01 05:38:11 max Exp $ - -DOC= ddwg -SRCS= ddwg.sgml - -.include <bsd.sgml.mk> diff --git a/en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml b/en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml deleted file mode 100644 index 9cb25739aa..0000000000 --- a/en_US.ISO_8859-1/tutorials/ddwg/ddwg.sgml +++ /dev/null @@ -1,1142 +0,0 @@ -<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> - -<!-- - ++++++++++++++++++++++++++++++++++++++++++++++++++ - ++ file: /home/erich/lib/src/sgml/ddwg.sgml - ++ - ++ Copyright Eric L. Hernes - Wednesday, August 2, 1995 - ++ - ++ $Id: ddwg.sgml,v 1.4 1997-10-03 20:53:38 wosch Exp $ - ++ - ++ Sgml doc for something - --> - -<article> - -<title>FreeBSD Device Driver Writer's Guide -<author>Eric L. Hernes, <tt/erich@rrnet.com/ -<date>Wednesday, May 29, 1996 - -<abstract> - -This document describes how to add a device driver to FreeBSD. It is -<it/not/ intended to be a tutorial on UNIX device drivers in general. -It is intended for device driver authors, familiar with the UNIX -device driver model, to work on FreeBSD. - -</abstract> - -<toc> - -<sect> 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_select() -<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_US.ISO_8859-1/tutorials/disklessx/Makefile b/en_US.ISO_8859-1/tutorials/disklessx/Makefile deleted file mode 100644 index 086d200c36..0000000000 --- a/en_US.ISO_8859-1/tutorials/disklessx/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -# $Id: Makefile,v 1.2 1997-07-01 05:38:12 max Exp $ - -DOCS= disklessx.sgml - -.include "../../web.mk" diff --git a/en_US.ISO_8859-1/tutorials/doc.ftr b/en_US.ISO_8859-1/tutorials/doc.ftr deleted file mode 100644 index 5f459de742..0000000000 --- a/en_US.ISO_8859-1/tutorials/doc.ftr +++ /dev/null @@ -1,5 +0,0 @@ -<hr> -<address> - <a href="../../mailto.html">www@freebsd.org</a> -</address> - diff --git a/en_US.ISO_8859-1/tutorials/doc.hdr b/en_US.ISO_8859-1/tutorials/doc.hdr deleted file mode 100644 index f5e32a9961..0000000000 --- a/en_US.ISO_8859-1/tutorials/doc.hdr +++ /dev/null @@ -1,14 +0,0 @@ -<IMG SRC="../../gifs/bar.gif" ALT="" WIDTH="565" HEIGHT="33" BORDER=0 usemap="#bar"> -<map name="bar"> -<area shape="rect" coords="1,1,111,31" href="../../index.html" ALT=""> -<area shape="rect" coords="112,11,196,31" href="../../ports/index.html" ALT=""> -<area shape="rect" coords="196,12,257,33" href="../../support.html" ALT=""> -<area shape="rect" coords="256,12,365,33" href="../../docs.html" ALT=""> -<area shape="rect" coords="366,13,424,32" href="../../commercial.html" ALT=""> -<area shape="rect" coords="425,16,475,32" href="../../search.html" ALT=""> -<area shape="rect" coords="477,16,516,33" href="../../index-site.html" ALT=""> -<area shape="rect" coords="516,15,562,33" href="../../index.html" ALT=""> -<area shape="rect" href="../../index.html" coords="0,0,564,32" ALT=""> -</map> - -<br clear=all> diff --git a/en_US.ISO_8859-1/tutorials/index.sgml b/en_US.ISO_8859-1/tutorials/index.sgml deleted file mode 100644 index d871cf95e2..0000000000 --- a/en_US.ISO_8859-1/tutorials/index.sgml +++ /dev/null @@ -1,49 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [ -<!ENTITY base CDATA ".."> -<!ENTITY date "$Date: 1998-02-21 16:14:40 $"> -<!ENTITY title "FreeBSD Tutorials"> -<!ENTITY % includes SYSTEM "../includes.sgml"> %includes; -]> -<!-- $Id: index.sgml,v 1.16 1998-02-21 16:14:40 eivind Exp $ --> - -<html> -&header; - - <p>Here lie assorted documents on various aspects of FreeBSD, - FreeBSD software, and hardware. If you have comments or - would like to contribute a document, please contact us at - <a href="mailto:freebsd-doc@FreeBSD.ORG">freebsd-doc@FreeBSD.org</a>.</p> - - <ul> - <li><a href="newuser/newuser.html">For People New to Both FreeBSD - <em>and</em> Unix</a></li> - - <li><a href="mh/mh.html">An introduction to the MH mail software</a></li> - - <li><a href="devel/devel.html">A User's Guide to FreeBSD Programming - Tools</a></li> - - <li><a href="ddwg/ddwg.html">Writing device drivers for FreeBSD</a> - (<a href="ddwg/ddwg.ps">postscript</a>, - <a href="ddwg/ddwg-html.tar.gz">gzipd tar file</a>)</li> - - <li><a href="ppp/ppp.html">Pedantic PPP primer - IP Aliasing</a> - (<a href="ppp/ppp.ps">postscript</a>, - <a href="ppp/ppp-html.tar.gz">gzipd tar file</a>)</li> - - <li><a href="multios/multios.html">Using FreeBSD with other operating systems</a></li> - - <li><a href="fonts/fonts.html">Fonts and FreeBSD</a></li> - - <li><a href="http://www.cypher.net/~black/ipalias.html">IP Aliasing</a></li> - <li><a href="http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html">Upgrading FreeBSD from source (using <b><tt>make world</tt></b>)</a></li> - <li><a href="diskformat/diskformat.html">Formatting Media For Use With FreeBSD -2.2-RELEASE</a></li> - - </ul> - - -&footer; -</body> -</html> - diff --git a/en_US.ISO_8859-1/tutorials/ppp/Makefile b/en_US.ISO_8859-1/tutorials/ppp/Makefile deleted file mode 100644 index 76ead715ae..0000000000 --- a/en_US.ISO_8859-1/tutorials/ppp/Makefile +++ /dev/null @@ -1,6 +0,0 @@ -# $Id: Makefile,v 1.2 1997-07-01 05:38:16 max Exp $ - -DOC= ppp -SRCS= ppp.sgml - -.include <bsd.sgml.mk> diff --git a/en_US.ISO_8859-1/tutorials/ppp/ppp.sgml b/en_US.ISO_8859-1/tutorials/ppp/ppp.sgml deleted file mode 100644 index b6ef36414b..0000000000 --- a/en_US.ISO_8859-1/tutorials/ppp/ppp.sgml +++ /dev/null @@ -1,1739 +0,0 @@ -<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> -<!-- $Id: ppp.sgml,v 1.5 1997-12-31 12:40:59 brian Exp $ --> - -<article> - -<title>PPP - Pedantic PPP Primer -<author>Maintainer: Steve Sims <tt><htmlurl -url="mailto:SimsS@IBM.NET" - name="<SimsS@IBM.NET>"></tt> - -<date>$Date: 1997-12-31 12:40:59 $ -<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/sysconfig</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/sysconfig</tt>. Use the -default text editor ('<tt/ee/') to edit this file. - -<p>Logged in as user 'root' load <tt>/etc/sysconfig</tt> into the -editor with the following command: -<tscreen><verb> -# ee /etc/sysconfig -</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> ---- -# Set to the name of your host - this is pretty important! -hostname=myname.my.domain ---- -</verb></tscreen> -Change this section to say (in our example): -<tscreen><verb> ---- -# Set to the name of your host - this is pretty important! -hostname=curly.my.domain ---- -</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/sysconfig</tt>. Use -the default text editor ('ee') to edit this file. - -<p>Logged in as user 'root' load <tt>/etc/sysconfig</tt> into the -editor with the following command: -<p> -<tt> # ee /etc/sysconfig</tt> -<p> -About 100 lines from the top of <tt>/etc/sysconfig</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" -</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" -</verb></tscreen> - -<p>(Note the space between the definition for the loopback device -("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/sysconfig</tt> file is a single -line that says: - -<tscreen><verb> -ifconfig_lo0="inet localhost" -</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/sysconfig</tt> to specify and -configure the network interfaces the section should look really close -to: - -<tscreen><verb> ---- -network_interfaces="lo0 ed0" -ifconfig_lo0="inet localhost" -ifconfig_ed0="inet 192.168.1.1 netmask 0xffffff00" ---- -</verb></tscreen> - -<p>Once all of the necessary changes to <tt>/etc/sysconfig</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/sysconfig</tt> file. -Load this file into your editor with the following command: -<tscreen><verb> -# ee /etc/sysconfig -</verb></tscreen> - -<p>About 250 lines down from the top of the file will be the -configuration -section which controls IP forwarding, which will look like: -<tscreen><verb> -===== -# If you want this host to be a gateway, set to YES. -gateway=NO -===== -</verb></tscreen> - -<p>Change this line to read: -<tscreen><verb> -===== -# If you want this host to be a gateway, set to YES. -gateway=YES -===== -</verb></tscreen> - -and exit the editor (saving the changes!). - -<p><em><bf>NOTE: This line may already be set to '<tt/gateway=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/sysconfig</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/sysconfig</tt>' as follows: - -<p> Using the '<tt/ee/' editor, load <tt>/etc/sysconfig</tt>. Scroll -down approximately 200 lines until you come to the section that says: -<tscreen><verb> ---- -# Set to appropriate flags for named, if you have a full-time -# connection to the Internet. -# For most hosts, flags should be "-b /etc/namedb/named.boot" -namedflags="NO" ---- -</verb></tscreen> -Change this section to read: -<tscreen><verb> ---- -# Set to appropriate flags for named, if you have a full-time -# connection to the Internet. -# For most hosts, flags should be "-b /etc/namedb/named.boot" -namedflags="-b /etc/namedb/named.boot" ---- -</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> - |