diff --git a/en_US.ISO8859-1/books/arch-handbook/book.sgml b/en_US.ISO8859-1/books/arch-handbook/book.sgml
index 880ca4c6ca..ccca2c6086 100644
--- a/en_US.ISO8859-1/books/arch-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/book.sgml
@@ -1,313 +1,313 @@
%bookinfo;
%man;
%chapters;
%authors
%mailing-lists;
]>
FreeBSD Developers' HandbookThe FreeBSD Documentation ProjectAugust 200020002001The FreeBSD Documentation Project
&bookinfo.legalnotice;
Welcome to the Developers' Handbook. This manual is a
work in progress and is the work of many
individuals. Many sections do not yet exist and some of those
that do exist need to be updated. If you are interested in
helping with this project, send email to the &a.doc;.The latest version of this document is always available
- from the FreeBSD World
+ from the FreeBSD World
Wide Web server. It may also be downloaded in a
variety of formats and compression options from the FreeBSD FTP
+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP
server or one of the numerous mirror
+ url="../handbook/mirrors-ftp.html">mirror
sites.Basics
&chap.introduction;
&chap.tools;
&chap.secure;
&chap.l10n;
&chap.policies;
Interprocess Communication* SignalsSignals, pipes, semaphores, message queues, shared memory,
ports, sockets, doors
&chap.sockets;
&chap.ipv6;
Kernel* History of the Unix KernelSome history of the Unix/BSD kernel, system calls, how do
processes work, blocking, scheduling, threads (kernel),
context switching, signals, interrupts, modules, etc.
&chap.locking;
&chap.kobj;
&chap.sysinit;
&chap.vm;
&chap.dma;
&chap.kerneldebug;
* UFSUFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling,
locking, metadata, soft-updates, LFS, portalfs, procfs,
vnodes, memory sharing, memory objects, TLBs, caching* AFSAFS, NFS, SANs etc]* SysconsSyscons, tty, PCVT, serial console, screen savers,
etc* Compatibility Layers* LinuxLinux, SVR4, etcDevice Drivers
&chap.driverbasics;
&chap.isa;
&chap.pci;
&chap.scsi;
&chap.usb;
* NewBusThis chapter will talk about the FreeBSD NewBus
architecture.* Sound subsystemOSS, waveforms, etcArchitectures
&chap.x86;
* AlphaTalk about the architectural specifics of
FreeBSD/alpha.Explanation of allignment errors, how to fix, how to
ignore.Example assembly language code for FreeBSD/alpha.* IA-64Talk about the architectural specifics of
FreeBSD/ia64.AppendicesDaveAPattersonJohnLHennessy1998Morgan Kaufmann Publishers,
Inc.1-55860-428-6Morgan Kaufmann Publishers, Inc.Computer Organization and DesignThe Hardware / Software Interface1-2W.RichardStevens1993Addison Wesley Longman,
Inc.0-201-56317-7Addison Wesley Longman, Inc.Advanced Programming in the Unix Environment1-2MarshallKirkMcKusickKeithBosticMichaelJKarelsJohnSQuarterman1996Addison-Wesley Publishing Company,
Inc.0-201-54979-4Addison-Wesley Publishing Company, Inc.The Design and Implementation of the 4.4 BSD Operating System1-2AlephOnePhrack 49; "Smashing the Stack for Fun and Profit"ChrispinCowanCaltonPuDaveMaierStackGuard; Automatic Adaptive Detection and Prevention of
Buffer-Overflow AttacksToddMillerTheode Raadtstrlcpy and strlcat -- consistent, safe string copy and
concatenation.
&chap.index;
diff --git a/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.sgml
index a65ec54238..e73fa17cc3 100644
--- a/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.sgml
@@ -1,391 +1,391 @@
Writing FreeBSD Device DriversThis chapter was written by &a.murray; with selections from a
variety of sources including the intro(4) man page by
&a.joerg;.IntroductionThis chapter provides a brief introduction to writing device
drivers for FreeBSD. A device in this context is a term used
mostly for hardware-related stuff that belongs to the system,
like disks, printers, or a graphics display with its keyboard.
A device driver is the software component of the operating
system that controls a specific device. There are also
so-called pseudo-devices where a device driver emulates the
behaviour of a device in software without any particular
underlying hardware. Device drivers can be compiled into the
system statically or loaded on demand through the dynamic kernel
linker facility `kld'.Most devices in a Unix-like operating system are accessed
through device-nodes, sometimes also called special files.
These files are usually located under the directory
/dev in the file system hierarchy. Until
devfs is fully integrated into FreeBSD, each device node must be
created statically and independent of the existence of the
associated device driver. Most device nodes on the system are
created by running MAKEDEV.Device drivers can roughly be broken down into two
categories; character and network device drivers.Dynamic Kernel Linker Facility - KLDThe kld interface allows system administrators to
dynamically add and remove functionality from a running system.
This allows device driver writers to load their new changes into
a running kernel without constantly rebooting to test
changes.The kld interface is used through the following
administrator commands :
kldload - loads a new kernel
modulekldunload - unloads a kernel
modulekldstat - lists the currently loadded
modulesSkeleton Layout of a kernel module/*
* KLD Skeleton
* Inspired by Andrew Reiter's Daemonnews article
*/
#include <sys/types.h>
#include <sys/module.h>
#include <sys/systm.h> /* uprintf */
#include <sys/errno.h>
#include <sys/param.h> /* defines used in kernel.h */
#include <sys/kernel.h> /* types used in module initialization */
/*
* Load handler that deals with the loading and unloading of a KLD.
*/
static int
skel_loader(struct module *m, int what, void *arg)
{
int err = 0;
switch (what) {
case MOD_LOAD: /* kldload */
uprintf("Skeleton KLD loaded.\n");
break;
case MOD_UNLOAD:
uprintf("Skeleton KLD unloaded.\n");
break;
default:
err = EINVAL;
break;
}
return(err);
}
/* Declare this module to the rest of the kernel */
static moduledata_t skel_mod = {
"skel",
skel_loader,
NULL
};
DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY);MakefileFreeBSD provides a makefile include that you can use to
quickly compile your kernel addition.SRCS=skeleton.c
KMOD=skeleton
.include <bsd.kmod.mk>Simply running make with this makefile
will create a file skeleton.ko that can
be loaded into your system by typing :
&prompt.root
kldload -v ./skeleton.koAccessing a device driverUnix provides a common set of system calls for user
applications to use. The upper layers of the kernel dispatch
these calls to the corresponding device driver when a user
accesses a device node. The /dev/MAKEDEV
script makes most of the device nodes for your system but if you
are doing your own driver development it may be necessary to
create your own device nodes with mknodCreating static device nodesThe mknod command requires four
arguments to create a device node. You must specify the name
of this device node, the type of device, the major number of
the device, and the minor number of the device.Dynamic device nodesThe device filesystem, or devfs, provides access to the
kernel's device namespace in the global filesystem namespace.
This eliminates the problems of potentially having a device
driver without a static device node, or a device node without
an installed device driver. Devfs is still a work in
progress, but it is already working quite nice.Character DevicesA character device driver is one that transfers data
directly to and from a user process. This is the most common
type of device driver and there are plenty of simple examples in
the source tree.This simple example pseudo-device remembers whatever values
you write to it and can then supply them back to you when you
read from it./*
* Simple `echo' pseudo-device KLD
*
* Murray Stokely
*/
#define MIN(a,b) (((a) < (b)) ? (a) : (b))
#include <sys/types.h>
#include <sys/module.h>
#include <sys/systm.h> /* uprintf */
#include <sys/errno.h>
#include <sys/param.h> /* defines used in kernel.h */
#include <sys/kernel.h> /* types used in module initialization */
#include <sys/conf.h> /* cdevsw struct */
#include <sys/uio.h> /* uio struct */
#include <sys/malloc.h>
#define BUFFERSIZE 256
/* Function prototypes */
d_open_t echo_open;
d_close_t echo_close;
d_read_t echo_read;
d_write_t echo_write;
/* Character device entry points */
static struct cdevsw echo_cdevsw = {
echo_open,
echo_close,
echo_read,
echo_write,
noioctl,
nopoll,
nommap,
nostrategy,
"echo",
33, /* reserved for lkms - /usr/src/sys/conf/majors */
nodump,
nopsize,
D_TTY,
-1
};
typedef struct s_echo {
char msg[BUFFERSIZE];
int len;
} t_echo;
/* vars */
static dev_t sdev;
static int len;
static int count;
static t_echo *echomsg;
MALLOC_DECLARE(M_ECHOBUF);
MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module");
/*
* This function acts is called by the kld[un]load(2) system calls to
* determine what actions to take when a module is loaded or unloaded.
*/
static int
echo_loader(struct module *m, int what, void *arg)
{
int err = 0;
switch (what) {
case MOD_LOAD: /* kldload */
sdev = make_dev(&echo_cdevsw,
0,
UID_ROOT,
GID_WHEEL,
0600,
"echo");
/* kmalloc memory for use by this driver */
/* malloc(256,M_ECHOBUF,M_WAITOK); */
MALLOC(echomsg, t_echo *, sizeof(t_echo), M_ECHOBUF, M_WAITOK);
printf("Echo device loaded.\n");
break;
case MOD_UNLOAD:
destroy_dev(sdev);
FREE(echomsg,M_ECHOBUF);
printf("Echo device unloaded.\n");
break;
default:
err = EINVAL;
break;
}
return(err);
}
int
echo_open(dev_t dev, int oflags, int devtype, struct proc *p)
{
int err = 0;
uprintf("Opened device \"echo\" successfully.\n");
return(err);
}
int
echo_close(dev_t dev, int fflag, int devtype, struct proc *p)
{
uprintf("Closing device \"echo.\"\n");
return(0);
}
/*
* The read function just takes the buf that was saved via
* echo_write() and returns it to userland for accessing.
* uio(9)
*/
int
echo_read(dev_t dev, struct uio *uio, int ioflag)
{
int err = 0;
int amt;
/* How big is this read operation? Either as big as the user wants,
or as big as the remaining data */
amt = MIN(uio->uio_resid, (echomsg->len - uio->uio_offset > 0) ? echomsg->len - uio->uio_offset : 0);
if ((err = uiomove(echomsg->msg + uio->uio_offset,amt,uio)) != 0) {
uprintf("uiomove failed!\n");
}
return err;
}
/*
* echo_write takes in a character string and saves it
* to buf for later accessing.
*/
int
echo_write(dev_t dev, struct uio *uio, int ioflag)
{
int err = 0;
/* Copy the string in from user memory to kernel memory */
err = copyin(uio->uio_iov->iov_base, echomsg->msg, MIN(uio->uio_iov->iov_len,BUFFERSIZE));
/* Now we need to null terminate */
*(echomsg->msg + MIN(uio->uio_iov->iov_len,BUFFERSIZE)) = 0;
/* Record the length */
echomsg->len = MIN(uio->uio_iov->iov_len,BUFFERSIZE);
if (err != 0) {
uprintf("Write failed: bad address!\n");
}
count++;
return(err);
}
DEV_MODULE(echo,echo_loader,NULL);To install this driver you will first need to make a node on
your filesystem with a command such as : &prompt.root mknod /dev/echo c 33 0With this driver loaded you should now be able to type
something like :&prompt.root echo -n "Test Data" > /dev/echo
&prompt.root cat /dev/echo
Test DataReal hardware devices in the next chapter..Additional Resources
Dynamic
Kernel Linker (KLD) Facility Programming Tutorial -
- Daemonnews October 2000
+ Daemonnews October 2000
How
to Write Kernel Drivers with NEWBUS - Daemonnews July
+ url="http://www.daemonnews.org/">Daemonnews July
2000Network DriversDrivers for network devices do not use device nodes in order
to be accessed. Their selection is based on other decisions
made inside the kernel and instead of calling open(), use of a
network device is generally introduced by using the system call
socket(2).man ifnet(), loopback device, Bill Paul's drivers,
etc..
diff --git a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml
index ca94063864..1598573616 100644
--- a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml
@@ -1,372 +1,372 @@
PCI DevicesThis chapter will talk about the FreeBSD mechanisms for
writing a device driver for a device on a PCI bus.Probe and AttachInformation here about how the PCI bus code iterates through
the unattached devices and see if a newly loaded kld will attach
to any of them./*
* Simple KLD to play with the PCI functions.
*
* Murray Stokely
*/
#define MIN(a,b) (((a) < (b)) ? (a) : (b))
#include <sys/types.h>
#include <sys/module.h>
#include <sys/systm.h> /* uprintf */
#include <sys/errno.h>
#include <sys/param.h> /* defines used in kernel.h */
#include <sys/kernel.h> /* types used in module initialization */
#include <sys/conf.h> /* cdevsw struct */
#include <sys/uio.h> /* uio struct */
#include <sys/malloc.h>
#include <sys/bus.h> /* structs, prototypes for pci bus stuff */
#include <pci/pcivar.h> /* For get_pci macros! */
/* Function prototypes */
d_open_t mypci_open;
d_close_t mypci_close;
d_read_t mypci_read;
d_write_t mypci_write;
/* Character device entry points */
static struct cdevsw mypci_cdevsw = {
mypci_open,
mypci_close,
mypci_read,
mypci_write,
noioctl,
nopoll,
nommap,
nostrategy,
"mypci",
36, /* reserved for lkms - /usr/src/sys/conf/majors */
nodump,
nopsize,
D_TTY,
-1
};
/* vars */
static dev_t sdev;
/* We're more interested in probe/attach than with
open/close/read/write at this point */
int
mypci_open(dev_t dev, int oflags, int devtype, struct proc *p)
{
int err = 0;
uprintf("Opened device \"mypci\" successfully.\n");
return(err);
}
int
mypci_close(dev_t dev, int fflag, int devtype, struct proc *p)
{
int err=0;
uprintf("Closing device \"mypci.\"\n");
return(err);
}
int
mypci_read(dev_t dev, struct uio *uio, int ioflag)
{
int err = 0;
uprintf("mypci read!\n");
return err;
}
int
mypci_write(dev_t dev, struct uio *uio, int ioflag)
{
int err = 0;
uprintf("mypci write!\n");
return(err);
}
/* PCI Support Functions */
/*
* Return identification string if this is device is ours.
*/
static int
mypci_probe(device_t dev)
{
uprintf("MyPCI Probe\n"
"Vendor ID : 0x%x\n"
"Device ID : 0x%x\n",pci_get_vendor(dev),pci_get_device(dev));
if (pci_get_vendor(dev) == 0x11c1) {
uprintf("We've got the Winmodem, probe successful!\n");
return 0;
}
return ENXIO;
}
/* Attach function is only called if the probe is successful */
static int
mypci_attach(device_t dev)
{
uprintf("MyPCI Attach for : deviceID : 0x%x\n",pci_get_vendor(dev));
sdev = make_dev(&mypci_cdevsw,
0,
UID_ROOT,
GID_WHEEL,
0600,
"mypci");
uprintf("Mypci device loaded.\n");
return ENXIO;
}
/* Detach device. */
static int
mypci_detach(device_t dev)
{
uprintf("Mypci detach!\n");
return 0;
}
/* Called during system shutdown after sync. */
static int
mypci_shutdown(device_t dev)
{
uprintf("Mypci shutdown!\n");
return 0;
}
/*
* Device suspend routine.
*/
static int
mypci_suspend(device_t dev)
{
uprintf("Mypci suspend!\n");
return 0;
}
/*
* Device resume routine.
*/
static int
mypci_resume(device_t dev)
{
uprintf("Mypci resume!\n");
return 0;
}
static device_method_t mypci_methods[] = {
/* Device interface */
DEVMETHOD(device_probe, mypci_probe),
DEVMETHOD(device_attach, mypci_attach),
DEVMETHOD(device_detach, mypci_detach),
DEVMETHOD(device_shutdown, mypci_shutdown),
DEVMETHOD(device_suspend, mypci_suspend),
DEVMETHOD(device_resume, mypci_resume),
{ 0, 0 }
};
static driver_t mypci_driver = {
"mypci",
mypci_methods,
0,
/* sizeof(struct mypci_softc), */
};
static devclass_t mypci_devclass;
DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);Additional Resources
- PCI
+ PCI
Special Interest GroupPCI System Architecture, Fourth Edition by
Tom Shanley, et al.Bus ResourcesFreeBSD provides an object-oriented mechanism for requesting
resources from a parent bus. Almost all devices will be a child
member of some sort of bus (PCI, ISA, USB, SCSI, etc) and these
devices need to acquire resources from their parent bus (such as
memory segments, interrupt lines, or DMA channels).Base Address RegistersTo do anything particularly useful with a PCI device you
will need to obtain the Base Address
Registers (BARs) from the PCI Configuration space.
The PCI-specific details of obtaining the BAR is abstracted in
the bus_alloc_resource() function.For example, a typical driver might have something similar
to this in the attach() function. : sc->bar0id = 0x10;
sc->bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &(sc->bar0id),
0, ~0, 1, RF_ACTIVE);
if (sc->bar0res == NULL) {
uprintf("Memory allocation of PCI base register 0 failed!\n");
error = ENXIO;
goto fail1;
}
sc->bar1id = 0x14;
sc->bar1res = bus_alloc_resource(dev, SYS_RES_MEMORY, &(sc->bar1id),
0, ~0, 1, RF_ACTIVE);
if (sc->bar1res == NULL) {
uprintf("Memory allocation of PCI base register 1 failed!\n");
error = ENXIO;
goto fail2;
}
sc->bar0_bt = rman_get_bustag(sc->bar0res);
sc->bar0_bh = rman_get_bushandle(sc->bar0res);
sc->bar1_bt = rman_get_bustag(sc->bar1res);
sc->bar1_bh = rman_get_bushandle(sc->bar1res);
Handles for each base address register are kept in the
softc structure so that they can be
used to write to the device later.These handles can then be used to read or write from the
device registers with the bus_space_*
functions. For example, a driver might contain a shorthand
function to read from a board specific register like this :
uint16_t
board_read(struct ni_softc *sc, uint16_t address) {
return bus_space_read_2(sc->bar1_bt, sc->bar1_bh, address);
}
Similarly, one could write to the registers with : void
board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
bus_space_write_2(sc->bar1_bt, sc->bar1_bh, address, value);
}
These functions exist in 8bit, 16bit, and 32bit versions
and you should use
bus_space_{read|write}_{1|2|4}
accordingly.InterruptsInterrupts are allocated from the object-oriented bus code
in a way similar to the memory resources. First an IRQ
resource must be allocated from the parent bus, and then the
interrupt handler must be setup to deal with this IRQ.Again, a sample from a device
attach() function says more than
words./* Get the IRQ resource */
sc->irqid = 0x0;
sc->irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &(sc->irqid),
0, ~0, 1, RF_SHAREABLE | RF_ACTIVE);
if (sc->irqres == NULL) {
uprintf("IRQ allocation failed!\n");
error = ENXIO;
goto fail3;
}
/* Now we should setup the interrupt handler */
error = bus_setup_intr(dev, sc->irqres, INTR_TYPE_MISC,
my_handler, sc, &(sc->handler));
if (error) {
printf("Couldn't set up irq\n");
goto fail4;
}
sc->irq_bt = rman_get_bustag(sc->irqres);
sc->irq_bh = rman_get_bushandle(sc->irqres);
DMAOn the PC, peripherals that want to do bus-mastering DMA
must deal with physical addresses. This is a problem since
FreeBSD uses virtual memory and deals almost exclusively with
virtual addresses. Fortunately, there is a function,
vtophys() to help.#include <vm/vm.h>
#include <vm/pmap.h>
#define vtophys(virtual_address) (...)
The solution is a bit different on the alpha however, and
what we really want is a function called
vtobus().#if defined(__alpha__)
#define vtobus(va) alpha_XXX_dmamap((vm_offset_t)va)
#else
#define vtobus(va) vtophys(va)
#endif
Deallocating ResourcesIt's very important to deallocate all of the resources
that were allocated during attach().
Care must be taken to deallocate the correct stuff even on a
failure condition so that the system will remain useable while
your driver dies.
diff --git a/en_US.ISO8859-1/books/corp-net-guide/book.sgml b/en_US.ISO8859-1/books/corp-net-guide/book.sgml
index b817f240f8..57d5532a5d 100644
--- a/en_US.ISO8859-1/books/corp-net-guide/book.sgml
+++ b/en_US.ISO8859-1/books/corp-net-guide/book.sgml
@@ -1,3213 +1,3213 @@
-
+
The FreeBSD Corporate Networker's GuideTedMittelstaedt2000Addison-Wesley Longman, IncISBN: 0-201-70481-1The eighth chapter of the book, The FreeBSD Corporate
Networker's Guide is excerpted here with the permission
of the publisher. No part of it may be further reproduced or
distributed without the publisher's express written
Chanda.Leary-Coutu@awl.com.
The other chapters of
- the
+ the
book covers topics such as system administration,
fileserving, and e-mail delivery. More information about this book is
available from the publisher, with whom you can also sign up to
receive news of related
titles. The author's web site for the book includes sample
code, working examples,
errata
and a Q&A forum, and is available at
http://www.freebsd-corp-net-guide.com/.PrintservingPrintserving is a complicated topic. There are many different
software interfaces to printers, as well as a wide variety of printer
hardware interfaces. This chapter covers the basics of setting up a
print queue, using Samba to print, and administering print queues and
connections.PC printing historyIn the early days of the personal computer, printing was simple.
The PC owner bought a cheap printer, usually a dot matrix that barely
supported ASCII, and plugged it into the computer with a parallel
cable. Applications would either work with the printer or not, and
most did because all they could do was output DOS or ASCII text. The
few software applications that supported graphics generally could only
output on specific makes and models of printers. Shared
network printing, if it existed, was usually done
by some type of serial port switchbox.This was the general state of affairs with the PC until the
Windows operating system was released. All at once, application
programmers were finally free of the restrictions of worrying about
how some printer manufacturer would change printer control codes.
Graphics printing, in the form of fonts and images, was added to most
applications, and demand for it rapidly increased across the
corporation. Large, high-capacity laser printers designed for office
printing appeared on the scene. Printing went from 150 to 300 to
600dpi for the common desktop laser printer.Today organizational network printing is complex, and printers
themselves are more complicated. Most organizations find that sharing
a few high-quality laser printers is much more cost effective than
buying many cheaper dot matrix units. Good network print serving is a
necessity, and it can be very well provided by the FreeBSD UNIX
system.Printer communication protocols and hardwarePrinters that don't use proprietary vendor codes communicate with
computers using one or more of three major printing protocols. The
communication is done over a hardware cable that can be a parallel
connection (printer port) or a serial connection (COM port).ASCII Printing ProtocolThe ASCII protocol is the simplest protocol used, as well as the
oldest. ASCII is also used to represent text files internally in
the DOS, UNIX, and Windows operating systems. Therefore, data taken
from a text file or a directory listing generally requires little
preparation before being sent to the printer, other than a
newline-to-carriage return/linefeed conversion for UNIX. Printers
usually follow the DOS text file convention of the print head
requiring an explicit carriage return character followed by a
linefeed character at the end of a line of text. Since UNIX uses
only the linefeed character to terminate text, an additional
carriage return character must be added to the end of each line in
raw text print output; otherwise, text prints in a
stairstep output. (Some printers have hardware
or software switches to do the conversion)PostScript Printing ProtocolAdobe introduced the PostScript language in 1985; it is used to
enable the printout of high quality graphics and styled font text.
PostScript is now the de-facto print standard in the UNIX community,
and the only print standard in the Macintosh community. Numerous
UNIX utilities exist to beautify and enhance
text printing with PostScript. PostScript can be used to download
font files into a printer as well as the data to be printed.
PostScript commands can be sent to instruct the printer CPU to
image, rotate, and scale complex graphics and images, thus freeing
the host CPU. Scaling is particularly important with fonts since
the document with the font has been produced on a computer screen
with far lower resolution than the printer. For example, a 1024x768
computer screen on a 17-inch monitor allows for a resolution of
approximately 82dpi, a modern desktop printer prints at a resolution
of 600dpi. Therefore, a font must be scaled at least seven times
larger for WYSIWYG output!PostScript printers generally come with a number of resident
fonts. For example, the NEC Silentwriter 95 contains Courier,
Helvetica, ITC Avant Garde Gothic Book, ITC Bookman Light, New
Century Schoolbook Roman, Palatino Roman, Times Roman, and several
symbol fonts. These are stored in Read Only Memory (ROM) in the
printer. When a page is printed from a Windows client that contains
a font not in the printer, a font substitution table is used. If no
substitute can be made, Courier is usually used. The user should be
conscious of this when creating documents - documents with fonts not
listed in the substitution table may cause other users problems when
printing. Avoid use of strange fonts for documents that will be
widely distributed.The user program can choose to download different fonts as
outline fonts to the PostScript printer if desired. Fonts that are
commonly used by the user are often downloaded to PostScript
printers that are connected directly to the user's computer, the
fonts are then available to successive print jobs until the printer
is turned off. When PostScript printers are networked, the clients
must download any fonts desired with each print
job. Since jobs come from different clients, the
clients cannot assume that downloaded fonts will still be in the
printer.PostScript print jobs also contain a header that is sent
describing the page layout, among other things. On a shared network
printer, this header must also be downloaded with each print job.
Although some PostScript drivers allow downloading of the header
only once, this usually requires a bi-directional serial connection
to the printer, instead of a unidirectional parallel
connection.PostScript print jobs can be sent either as binary data or as
ASCII. The main advantage of binary data transmission is that it is
faster. However, not all PostScript printers support it. Also,
fonts can generally not be downloaded in binary. When FreeBSD is
used as a printserver, ASCII PostScript printing should be selected
on the clients, this is generally the default with most PostScript
drivers.The Adobe company licenses PostScript interpreters as well as
resident fonts to printer manufacturers, and extracts a hefty
license fee from any printer manufacturer who wants to use them in
its printer. This presents both a benefit and a problem to the end
user. Although a single company holding control over a standard can
guarantee compliance, it does significantly raise the cost of the
printer. As a result, PostScript has not met with much success in
lower-end laser and inkjet Windows printing market, despite the fact
that Adobe distributes PostScript software operating system drivers
for free.One issue that is a concern when networking PostScript printers
is the selection of banner page, (also known as header page, or
burst page) printing. UNIX shared printing
began with ASCII line printers, and since UNIX is a multiuser
system, often many different user print jobs piled up in the printer
output hopper. To separate these jobs the UNIX printing system
programs support banner page printing if the client program that
submits jobs asks for them. These pages print at the beginning or
end of every print job and contain the username, submittal date, and
so on.. By default, most clients, whether remote (e.g., a Windows
LPR client) or local (e.g., the /usr/bin/lpr
program) trigger a banner page to be printed. One problem is that
some PostScript printers abort the entire job if they get
unformatted ASCII text instead of PostScript. (In general,
PostScript printers compatible with Hewlett-Packard Printer Control
Language [HPPCL] handle banners without problems) Banner printing
should be disabled for any printers with this problem, unless
PostScript banner page printing is set up on the server.HPPCL Printing ProtocolThe Hewlett Packard company currently holds the largest market
share of desktop inkjet and office laser printers. Back when
Windows was released, HP decided to expand into the desktop laser
jet market with the first LaserJet series of printers. At the time
there was much pressure on Microsoft to use Adobe Type Manager for
scaleable fonts within Windows, and to print PostScript to
higher-end printers. Microsoft decided against doing this and used
a technically inferior font standard, Truetype. They thought that
it would be unlikely that the user would download fonts to the
printer, since desktop Publishing was not being done on PC's at the
time. Instead users would rasterize the entire page to the printer
using whatever proprietary graphics printer codes the selected
printer needed. HP devised HPPCL for their LaserJets, and make
PostScript an add-on. The current revision of HPPCL now allows for
many of the same scaling and font download commands that PostScript
does. HP laser jet printers that support PostScript can be
distinguished by the letter "M" in their model number. (M is for
Macintosh, since Macintosh requires PostScript to print) For
example, the HP 6MP has PostScript, the 6P doesn't.HPPCL has almost no support in the UNIX applications market, and
it is very unlikely that any will appear soon. One big reason is
the development of the free Ghostscript
PostScript interpreter. Ghostscript can
take a PostScript input stream and print it on a PCL printer under
UNIX. Another reason is the UNIX community's dislike of reinventing
the wheel. HPPCL has no advantage over PostScript, and in many ways
there are fewer problems with PostScript. Considering that
PostScript can be added to a printer, either by hardware or use of
Ghostscript, what is the point of
exchanging an existing working solution for a slightly technically
inferior one? Over the life of the printer, taking into account the
costs of toner, paper, and maintenance, the initial higher cost of
PostScript support is infinitesimal.Network Printing BasicsThe most common network printing implementation is a printserver
accepting print jobs from clients tied to the server via a network
cable.PrintserversThe term "printserver" is one of those networking terms, like
packet, that has been carelessly tossed around
until it's meaning has become somewhat confusing and blurred. To be
specific, a printserver is simply a program that arbitrates print
data from multiple clients for a single printer. Printservers can
be implemented in one of the four methods described in the following
sections.Printserver on the fileserverThe printer can be physically cabled to the PC running the
Network OS. Print jobs are submitted by clients to the
printserver software on the fileserver, which sends them down the
parallel or serial cable to the printer. The printer must be
physically close to the fileserver. This kind of printserving is
popular in smaller workgroup networks, in smaller offices.Printserver on the fileserver ,---------.
| ======= | Server
| ======= | +---------------------+ ,-----.
+-----------+ | +---------------+ | | |
| Printer [ ]------------[ ] | Printserver | | |_____|
+-----------+ Parallel | | Software | [ ]------_________
Cable | +---------------+ | / ::::::: \
+---------------------+ `---------'
Network PCPrinter, connected to a network server running
printserver software, with one or more network PCs printing
through it.Printserver on a separate PCIt is possible to run a print server program on a cheap PC
that is located next to the printer and plugged into it via
parallel cable. This program simply acts as a pass-through
program, taking network packets from the network interface and
passing them to the printer. This kind of server doesn't allow
any manipulation of print jobs, jobs usually come from a central
fileserver, where jobs are controlled.Printserver on a separate PC Fileserver
,----------------.
,---------. .---| | === |
| ======= | ,-----. | `----------======'
| ======= | | | |
+-----------+ |_____| |
| Printer [ ]------------_________---------| Ethernet
+-----------+ Parallel / ::::::: \ |
Cable `---------' |
Printserver | ,-----.
| | |
| |_____|
`---------_________
/ ::::::: \
`---------'
Network PCPrinter connected to a printserver (typically running
FreeBSD), with network files hosted on a separate machine,
and a network PC, able to access both resources.Printserver on a separate hardware boxA printserver on a separate hardware box is exemplified by
network devices such as the Intel Netport, the HP JetDirect Ex,
the Osicom/DPI NETPrint, and the Lexmark MarkNet. Basically, these
are plastic boxes with an Ethernet connection on one side and a
parallel port on the other. Like a printserver on a PC, these
devices don't allow remote job manipulation, and merely pass
packets from the network down the parallel port to the
printer.Printserver on a separate hardware box Fileserver
,----------------.
,---------. .---| | === |
| ======= | | `----------======'
| ======= | Printserver |
+-----------+ ,--------. |
| Printer [ ]-----------[ ] ooo [ ]-------| Ethernet
+-----------+ Parallel `--------' |
Cable |
| ,-----.
| | |
| |_____|
`---------_________
/ ::::::: \
`---------'
Network PCPrinter connected to a dedicated print server
appliance.Printserver in the PrinterThe HP JetDirect Internal is the best known printserver of
this type. It is inserted into a slot in the printer case, and it
works identically to the external JetDirect units.Printeserver in the printer Fileserver
,----------------.
,---------. .---| | === |
| ======= | | `----------======'
| ======= | |
+-----------+ |
| Printer [ ]------------------------------| Ethernet
+-----------+ |
|
| ,-----.
| | |
| |_____|
`---------_________
/ ::::::: \
`---------'
Network PCPrinter with an embedded print server, connecting
directly to the local network.PrintspoolsPrintspooling is an integral part of network printing. Since
the PC can spit out data much faster than the printer can accept it,
the data must be buffered in a spool at some location. In addition,
because many clients share printers, when clients send print jobs at
the same time, jobs must be placed on a queue so that one can be
printed after the other.Logical location of the print spoolPrintspooling can be implemented at one of three
locationsThe client. Clients can be required to spool their own
print jobs on their own disks. For example, when a Windows
client application generates a print job the job must be
placed on the local client's hard drive. Once the remote
print server is free to accept the job it signals the client
to start sending the job a bit at a time. Client spooling is
popular in peer-to-peer networks with no defined central
fileserver. However, it is impossible for a central
administrator to perform advanced print job management tasks
such as moving a particular print job ahead of another, or
deleting jobs.The printserver. If each printer on the network is
allocated their own combination print spooler-printserver,
jobs can stack at the printer. Many of the larger printers
with internal printservers have internal hard disks for this
purpose. Although this enables basic job management, it still
restricts the ability to move jobs from one printer to
another.A central print spooler on a
fileserver. Print jobs are received from all
clients on the network in the spool and then dispatched to the
appropriate printer. This scheme is the best for locations
with several busy printers and many clients. Administration
is extremely simple because all print jobs are spooled on a
central server, which is particularly important in bigger
organizations. Many large organizations have standardized on
PostScript printing for all printing; in the event that a
particular printer fails and is offline, incoming PostScript
print jobs can be rerouted automatically to another printer.
Since all printers and clients are using PostScript, clients
don't need to be reconfigured when this happens. Print jobs
appear the same whether printed on a 4 page-per-minute NEC
Silentwriter 95, or a 24 page-per-minute HP LaserJet 5SiMX if
both printers are defined in the client as PostScript
printers.Print spool locations Client
,---------. PC
| ======= | ,-----.
| ======= | | |
+-----------+ |_____|
| Printer [ ]---------------------------------------------------_________
+-----------+ / ::::::: \
`---------'
Spool
Printserver
,---------. PC
| ======= | ,-----.
| ======= | | |
+-----------+ ,----------------. |_____|
| Printer [ ]--------------| | === |-------------------_________
+-----------+ `----------======' / ::::::: \
Spool `---------'
Fileserver
,---------. PC
| ======= | ,-----.
| ======= | Printserver Fileserver | |
+-----------+ ,----------------. ,----------------. |_____|
| Printer [ ]----| | === |-----| | === |------_________
+-----------+ `----------======' `----------======' / ::::::: \
Spool `---------'Possible locations for the print spoolFreeBSD is an excellent platform to implement centralized
printserving and print spooling. The rest of this chapter
concentrates on the centralized print spooler model. Note that
PostScript printing is not a requirement for this model--the HPPCL
protocol can be the standard print protocol as well. For
transparent printing between printers with HPPCL, however, the
printer models must be similar.Physical location of the print spoolIn some companies, the central fileserver is often placed in a
closet, locked away. Printers, on the other hand, are best
located in high traffic areas for ease of use. Network printing
works best when the printers are evenly distributed throughout the
organization. Attempting to place all the major printers in one
location, as technically advantageous as it may seem, merely
provokes users to requisition smaller printers that are more
convenient for that quick print job. The administrator may end up
with a datacenter full of nice, expensive printers that are never
used, while the smaller personal laser printers scattered
throughout the plant bear most of the printing load.The big problem with this is that scattering printers through
the organization makes it difficult to utilize the 3 possible
parallel ports on the fileserver due to parallel port distance
limitations. Although high-speed serial ports may extend the
distance, not many printers have good serial ports on them. This
is where the hardware network print server devices can come into
play. I prefer using these devices because they are much cheaper
and more reliable than a standalone PC running printserver
software. For example, Castelle
- http://www.castelle.com
+ http://www.castelle.com/
sells the LANpress 1P/10BT printserver for about $170.00. Using
these devices a FreeBSD UNIX server can have dozens of print spools
accepting print jobs and then route them back out over the network
to these remote printserver boxes. If these hardware servers are
used, they must support the Line Printer Daemon (LPD) print
protocol.With a scheme like this it is important to have enough disk
space on the spool to handle the print jobs. A single large
PowerPoint presentation PostScript print job containing many
graphics may be over 100MB. When many such jobs stack up in the
print spool waiting to print, the print spooler should have
several gigabytes of free disk space available.Network Printing to Remote SpoolsAlthough several proprietary network printing protocols such
as Banyan Vines and NetWare, are tied to proprietary protocols,
FreeBSD Unix can use two TCP/IP network printing protocols to
print to remote print spools. The two print protocols available
on TCP/IP with FreeBSD are the open LPD protocol and the
NetBIOS-over-TCP/IP Server Messaging Block (SMB) print protocol
first defined by Intel and Microsoft and later used by IBM and
Microsoft.The LPD protocol is defined in RFC1179 This network protocol
is the standard print protocol used on all UNIX systems. LPD
client implementations exist for all Windows operating systems and
DOS. Microsoft has written LPD for the Windows NT versions, the
other Windows operating system implementations are provided by
third parties.The Microsoft Networking network protocol that runs on top of
SMB can use NetBIOS over TCP/IP as defined in RFC1001 and RFC1002.
This protocol has a specification for printing that is the same
print protocol used to send print jobs to NT Server by Microsoft
clients. To implement this protocol on FreeBSD requires the
installation of the Samba client suite of programs discussed in
Chapter 7.Setting up LPR on Windows clientsThe program clients use to print via LPD is the Line Printer
Remote, or LPR program. The following instructions cover enabling
this program on Windows clients.Windows 3.1/Windows for Workgroups 3.11Several commercial TCP/IP stacks are available for Win31, that
provide LPR client programs, in addition to the basic TCP/IP
protocol to Win31. WfW has TCP/IP networking available for free
from Microsoft, but it doesn't include an LPR client. Unfortunately,
I have not come across a freeware implementation of a 16-bit Windows
LPR client, so with the following instructions I use the Shareware
program WLPRSPL available from http://www.winsite.com/info/pc/win3/winsock/wlprs41.zip.
This program must be active during client printing, and is usually
placed in the Startup group.Organizations that want to use UNIX as a printserver to a group
of Win31 clients without using a commercial or shareware LPR program
have another option. The Microsoft Networking client for DOS used
underneath Win31 contains SMB-based printing which is covered later
in the chapter. DOS networking client setup and use are covered in
Chapter 2 and Chapter 7.If LPR-based client printing is desired and the organization
doesn't want to upgrade to Win95, (which has several LPR clients
available) the following instructions can be used. WLPRSPL needs a
Winsock under Windows 3.1, so for the example I explain the setup of
the Novell 16-bit TCP/IP client. The stack can be FTPed from
Novell, and is easy to integrate into sites that already use the
16-bit NetWare networking client, usually NW 3.11 and 3.12. In most
cases, however, sites that use NetWare + Win31 are probably best off
printing through the NetWare server, then loading an LPR spooler as
an Netware Loadable Module (NLM) to send the job over to
FreeBSD.As an alternate, the Microsoft Networking DOS 16-bit TCP/IP
client under Win31 contains a Winsock, as does Microsoft TCP/IP for
WfW. The target machine used here is a Compaq Deskpro 386/33 with
12MB of ram with an operating version of Windows 3.1, and a 3com
3C579 EISA network card. The instructions assume an LPR printserver
on the network, named mainprinter.my.domain.com
with a print queue named RAW.Use the installation instructions in Exhibit 8.1 for a quick and
dirty TCP/IP Winsock for Win31 systems. Administrators who already
have the Novell IPX client installed should skip those steps.Installation of the Novell TCP/IP Winsock clientMake sure that the machine has enough environment space
(2048 bytes or more) by adding the following line to the
config.sys file and rebooting:SHELL=C:\COMMAND.COM /E:2048 /PObtain the TCP16.EXE file from
- ftp3.novell.com/pub/updates/eol/nweol/tcp16.exe.
+ ftp://ftp3.novell.com/pub/updates/eol/nweol/tcp16.exe.
Obtain the Network Adapter support diskette for the network
card in your machine. This should be supplied with the card, or
available via FTP from the network adapter manufacturer's FTP
site.Now you need the file LSL.COM. This is
available on some Network Adapter Driver diskettes, it used to
be available from the VLM121_2.EXE file
from Novell but unfortunately this file is no longer publicly
accessible from Novell.If you have vlm121_2.exe in a temporary
directory, run it. This will extract a number of files.One of the files extracted is LSL.CO_
extract this file with the command nwunpack
lsl.co_.Create the directory c:\nwclient. Then,
copy lsl.com from the temporary directory
into the directory.Obtain and install the printer driver for the model of
printer that you will be spooling to and point it to
LPT1:. Win31 and WfW 3.11 have an
incomplete printer driver list, so if you need a driver
Microsoft has many Win16 printer drivers on their FTP site. A
list is available at
ftp://ftp.microsoft.com/Softlib/index.txt.
In addition, if you are installing a PostScript printer driver
for a printer supplied in Win31, it may be necessary to patch
the driver. The Microsoft PostScript driver supplied in Win31
is version 3.5. (The patch named
PSCRIP.EXE which brought the PostScript
driver to version 3.58 is no longer publicly available.) WfW
already uses the more recent PostScript driver, as does Win31
version A. Installing the Adobe Postscript driver for Win31 is
also an option. (see
http://www.adobe.com/support/downloads/pdrvwin.htm
for the version 3.1.2 Win31 PostScript driver).Look on the network adapter driver disk for the subdirectory
nwclient/ and then look for the ODI driver
with the adapter card. For example, on the 3com 3C509/3C579
adapter driver disk, the driver and location are
\NWCLIENT\3C5X9.COM. Copy this driver to
the c:\nwclient directory.Create a file called NET.CFG in the
c:\nwclient directory. Often, the network
card adapter driver diskette has a template for this file in the
same location as the ODI driver. This can be modified, as can
the following example:LINK SUPPORT
BUFFERS 4 1600
MEMPOOL 8192
LINK DRIVER
3C5X9
; PORT 300 (these are optional, if needed by card uncomment)
; INT 10 (optional, uncomment and modify if needed)Attempt to load the network card driver. First load
lsl, then the ODI driver. With the 3com
card the commands are:lsl3c5x9If the driver properly loads it will list the hardware port
and interrupt settings for the network adapter. If it has
loaded properly, unload the drivers in reverse order with the
command:3c5x9 /ulsl /uGo to the temporary directory that contains the
tcp16.exe file and extract it by running
the program.Run the install batch file by typing
installr. It should list New
Installation detected. It will then copy a number
of files into nwclient, add some
commented-out sections to net.cfg, and call
edit on net.cfg.Read the editing instructions and make the appropriate
entries. The sample net.cfg file from
above would look like this.LINK SUPPORT
BUFFERS 4 1600
MEMPOOL 8192
LINK DRIVER 3C5X9
FRAME ETHERNET_II
Protocol TCPIP
PATH TCP_CFG c:\nwclient
ip_address 192.168.1.54 LAN_NET
ip_netmask 255.255.255.0 LAN_NET
ip_router 192.168.1.1 LAN_NET
Bind 3C5X9 #1 Ethernet_II LAN_NETSave and exit, the Installer should list TCP16
installation completed.Reload the client with the commands:lsl3c5x9tcpipThe TCPIP driver should list the IP numbers and other
information.Optionally, create either a HOSTS file,
or a RESOLV.CFG file (pointing to a
nameserver) in c:\nwclient. Check to see
this is operating properly by pinging a hostname.Add the c:\nwclient directory to the
PATH, as well as the 3 startup commands in step
15 in autoexec.batInstallation of the LPR client on 16-bit Windows with a Winsock
installedThe following assumes a running Win31 installation with a
Winsock or a running WfW installation with the 32-bit Microsoft
TCP/IP protocol installed.Install the printer driver desired. See step 8 of the
previous set of instructions.Obtain and extract into a temporary directory the
wlprs41.zip file from the location
mentioned above.Run setup.exe from the temporary
directory containing the wlprs files
are.In setup, accept default directory, and check Yes to add to
its own group. Click Continue when asked
for group name, and check whatever choice you want when asked to
copy the doc files.Click No when asked to add the
program to Startup.On the Unix FreeBSD print spooler, make sure that there is
an entry in /etc/hosts.lpd or
/etc/hosts.equiv for the client
workstation, thereby allowing it to submit jobs.Double-click the Windows LPR Spooler icon in the Windows LPR
Spooler group that is opened. When it asks for a valid spool
directory, just select the c:\wlprspl
directory that the program installed its files into.When asked for a valid Queue Definition File, just click
OK to use the default filename. The
program automatically creates a queue definition file.The program opens up with it's menu. Click
Setup in the top menu, then select
Define New Queue.For a local spool filename, just use the name of the remote
queue (RAW) to which the client prints.For the remote printer name, use the same name as the remote
queue (RAW) to which the client prints.For the remote hostname, use the machine name
of the FreeBSD print spooler.
mainprinter.ayedomain.com.For the Description, enter a description such as
3rd floor Marketing printer.For the protocol, leave the default of BSD LPR/LPD
selected.Click on the Queue Properties,
and make sure that the Print unfiltered is
selected. If you're printing PostScript, then also click the
Advanced options button. Make sure that
Remove trailing Ctrl-D is
unchecked, and that Remove
Leading Ctrl-D is checked.
Also with PostScript, if the printer cannot print ASCII, uncheck
the Send header page box. (PostScript
header/banner pages are discussed later in this chapter)Click OK. At the main menu of the
program, click File, then Control
Panel/Printers to bring up the Printers control
panel of Windows.Make sure that the Use Print Manager
button is checked, then highlight the printer driver and click
the Connect button.Scroll down to the C:\WLPRSPL\RAW entry
for the spool that was built and highlight this. Click
OK.Minimize the Windows LPR Spooler. Copy the Windows LPR
Spooler icon to the Startup group. Click
File/Properties with the Windows LPR Spooler
icon highlighted in the Startup group. Check the Run
Minimized button.Exit Windows, and when the Save queue
changes? button comes up, click
Yes.Restart windows and make sure that the spooler starts
up.Open the Control Panel and look for a new yellow icon named
Set Username If you are running the Novell or
other Winsock under Win31, click on this icon and put the
username of the person using this computer into the space
provided. If you are running WfW, this isn't necessary because
Windows will supply the username.If the spooler is not started properly in some
installations, there may be a bug. If placing the icon in the
StartUp group doesen't actually start the spooler, the program
name can be placed in the run= line of
win.ini.Try printing a print job from an application such as
Notepad. If everything goes properly, clicking on the
Queues/Show remote printer status" in
the Windows LPR menu should show the print job spooled and
printing on the remote printserver.Installation of LPR client on Windows 95/98The wlprspl program also can be used under
Windows 95, but as a 16-bit program, it is far from an optimal
implementation on a 32-bit operating system. In addition, Win95 and
it's derivatives fundamentally changed from Windows 3.1 in the
printing subystem. For these reasons I use a different LPR client
program for Win95/98 LPR printing instructions. It is a full 32-bit
print program, and it installs as a Windows 32-bit
printerport monitor. The program
is called ACITS LPR Remote Printing for Windows 95 and it is located
at http://shadowland.cc.utexas.edu/acitslpr.htm.ACITS stands for Academic Computing and Instructional
Technologies Services. The ACITS LPR client includes software
developed by the University of Texas at Austin and its contributors,
it was written by Glenn K. Smith, a systems analyst with the
Networking Services group at the university. The filename of the
archive in the original program was ACITSLPR95.EXE and as of version
1.4 it was free for individuals or organizations to use for their
internal printing needs. Since that time, it has gotten so popular
that the university has taken over the program, incremented the
version number (to get out from under the free license) and is now
charging a $35 per copy fee for commercial use for the newer
versions. The older free version can still be found on overseas FTP
servers, such as http://www.go.dlr.de/fresh/pc/src/winsock/acitslpr95.exe.It is likely that the cost of a shareware/commercial LPR program
for Win95 plus the cost of Win95 itself will meet or exceed that of
Win2K. As such, users wishing to print via LPR to FreeBSD UNIX
systems will probably find it cheaper to simply upgrade to Windows
NT Workstation or Win2K.ACITS LPR and Win95 have a few printing idosyncracies. Most
Win95 programs, such as Microsoft Word, expect print output to be
spooled on the local hard drive and then metered out to a printer
that is plugged into the parallel port. Network printing, on the
other hand, assumes that print output will go directly from the
application to the remote print server. Under Win95, local ports
have a setting under Properties, Details, Spool Settings labeled
"Print directly to the printer". If this is checked, the
application running on the desktop (such as Microsoft Word) will not
create a little Printer icon with pages coming out of it or use
other means of showing the progress of the job as it is built. This
can be very disconcerting to the user of a network printer, so this
option should be checked only with printers plugged directly into
the parallel port. Worse, if this is checked with ACITS, it can
cause the job to abort if the remote print spooler momentarily goes
offline.Another local setting also should be changed. Generally, with
local ports, Win95 builds the first page in the spooler and then
starts printing it while the rest of the pages spool. If ACITS
starts printing the first page while the rest of the pages are
building, timeouts at the network layer can sometimes cause very
large jobs to abort. The entire job should be set to completely
spool before the LPR client passes it to the Unix spooler. The
problem is partly the result of program design: because ACITS is
implemented as a local printer port instead of being embedded into
Win95 networking (and available in Network Neighborhood) the program
acts like a local printer port in some ways.The LPR program can be set to deselect banner/burst page
printing if a PostScript printer that cannot support ASCII is used.
The burst pages referred to here are NOT generated by the Windows
machine. Use the instructions in Exhibit 8.3 to installLPR client on Win95/98 installation instructionsObtain the ACITSLPR95.EXE file and
place it in a temporary directory such as
c:\temp1.Close all running programs on the desktop. The computer
must be rebooted at completion of
installation or the program will not work.Click Start,
Run and type in
c:\temp1\acitslpr95 then click
Yes at the InstallShield prompt.Click Next, then
Yes. The program will run through some
installation and then presents a Help screen that explains how
to configure an LPR port.After the help screen closes, the program asks to reboot the
system. Ensure that Yes is checked and
click Finish to reboot.After the machine comes back up, install a Printer icon in
the Start, Settings,
Printers folder if one hasn't been
created for the correct model of destination printer.With the Printers folder open, right-click over the printer
icon that needs to use the LPR program and click on the
Properties tab.Under the Details tab, click the
Add Port tab, then click
Other.Highlight the ACITS LPR Remote Printing
line and click OK.The Add ACITS LPR screen opens. Type in the hostname of the
UNIX system that the client spools through—
mainprinter.ayedomain.com.Type in the Printer/Queue name and click
OK. (Some versions have a "Verify Printer
Information" button.) The LPR program then contacts the UNIX
host and makes sure that the selected printer is
available.If this fails the client machine name is probably not in
the /etc/hosts.equiv or
etc/hosts.lpd on the FreeBSD printserver.
Most sites may simply decide to put a wildcard in
hosts.equiv to allow printing, especially
if DHCP is used, but many security-conscious sites may stick
with individual entries in
hosts.lpd.If the printer is PostScript and cannot print ASCII, make
sure that the "No banner page control flag" is checked to turn
off banner pages. Accessible under Port settings, this flag is
overridden if the /etc/printcapfile
specifies no banner pages.Review how the "send plain text control flag" is set. With
this flag unchecked, the LPR code sent is L, (ie:, print
unfiltered) meaning that the if filter gets
called with the option. This is equivalent
to the local invocation of /usr/bin/lpr -l.
With the flag checked, the code is F, (formatted) meaning that
the iffilter gets called without the
option. This is equivalent to the default
invocation /usr/bin/lpr. (This is also an
issue under Windows NT, which retypes the print job to text if
this flag is checked. Some filters understand the
flag, which is used to preserve control
characters, so it should generally remain unchecked.Leave the "Send data file before control file" box
unchecked. This option is used only in rare mainframe spooling
circumstances.Click OK, then click the
Spool Settings button at the properties
page.Make sure that the "Spool print jobs so program finishes
printing faster" box is checked.Make sure that "Start printing after last page is spooled"
box is checked.Make sure that "Disable bi-directional support for this
printer" is checked, or greyed out.Make sure that the "Spool data format" is set to RAW. Some
printer drivers present a choice of EMF or RAW, such as the
Generic Text driver, in this case select RAW.Click OK, then
OK again to close the Printer Properties.
The printer icon now spools through FreeBSD.Installation of LPR client on Windows NTUnlike WfW and Win95 TCP/IP, Windows NT—both server and
workstation—includes an LPR client as well as an LPD program
that allows incoming print jobs to be printed from LPR clients, such
as UNIX systems.To install the LPR client and daemon program under Windows NT
3.51, use the following instructions. The TCP/IP protocol should be
installed beforehand and you must be logged in to the NT system as
Administrator. This can be done at any time after the NT system is
installed, or during OS installation:Double-click on Main, Control Panel, then
Network Settings.In the Installed Network Software window, "Microsoft TCP/IP
Printing" should be listed as well as "TCP/IP Protocol".Click the Add Software button to get
the Add Network Software dialog boxClick the down arrow and select TCP/IP Protocol and related
components. Click Continue.Check the "TCP/IP Network Printing Support" box and click
Continue. LPR printing is now installed.
Follow the instructions to reboot to save changes.To install the LPR client and daemon program under Windows NT 4,
use the following instructions. The TCP/IP protocol should be
installed beforehand and you must be logged in to the NT system as
Administrator. This can be done at any time after the NT system is
installed, or during OS installation:Click on Start,
Settings, Control
Panel, and double-click on
Network to open it up.Click on the Services tab.
Microsoft TCP/IP Printing should be listed.
If not, continue steps 3 - 4.Click Add, then select
Microsoft TCP/IP Printing and click
OK.Click Close. Follow instructions to
reboot to save changes.Any NT Service Packs that were previously installed must
be reapplied after these operations.Once LPR printing has been installed, the Printer icon or icons
must be created on the NT system so that applications can print.
Since this printer driver does all job formatting before passing the
printing to the FreeBSD printserver, the print queues specified
should be raw queues on the FreeBSD system, which don't do any job
formatting.To install the printer icon in Print Manager and set it to send
print jobs to the FreeBSD UNIX system, use the following
instructions under NT 3.51. You must be logged in to the NT system
as Administrator. This can be done at any time after the NT system
is installed, or during OS installation.Click on Main, and open it. Then click on Print Manager to
open it.Click on Printer, Create
Printer. Select the appropriate printer
driver.Click the down arrow under Print To and select
Other.In the Available Print Monitors window select
LPR port and click OK.Enter the hostname of the FreeBSD printserver, and the name
of the printer queue and click OKClick OK to close the Create Printer
window. The Printer icon is created.To install the printer icon in Print Manager and set it to send
print jobs to the FreeBSD UNIX system, use the following
instructions under NT 4. You must be logged in to the NT system as
Administrator. This can be done at any time after the NT system is
installed, or during OS installation:Click Start,
Settings,
Printers to open the printer
folder.Double-click Add Printer to start the
wizard.3) Select the My Computer radio button, not the Network
Print Server button and click Next. (The
printer is a networked printer, it is
managed on the local NT system. Microsoft used confusing
terminology here.Click Add Port and select LPR Port,
then click New Port.Enter the hostname and print queue for the FreeBSD
printserver and click OK.Click Next and select the correct
printer driver. Continue until the printer is set up.The LPR client in Windows NT allows DOS print jobs originating
in DOS boxes to be routed to the central UNIX print spooler. This
is an advantage over the Win95 and WfW LPR programs.Windows NT Registry ChangesUsing the LPR daemon program under Windows NT presents one
problem. If the NT server is used as an LPR/LPD "relay", for
example, to pass jobs from clients to LPR print queues on a UNIX
system, to pass jobs from LPR programs on UNIX terminating at NT
print queues, or to pass jobs from Appletalk clients to LPR
printers, NT retypes the job if the type code is set to P (text).
This can wreak havoc on PostScript files printed through HP
LaserJet printers with internal MIO cards in them, if the job
originates from the /usr/bin/lpr program
under UNIX, which assigns a P type code. The printserver card
treats PostScript jobs as text, and instead of the print job, the
raw PostScript codes print. This problem often manifests in the
following way: /usr/bin/lpr is used to print
a PostScript file from UNIX directly to the remote printer
printserver, which works fine, but spooling it through NT causes
problems.A registry change that can override the NT Server formatting
behavior is detailed in Microsoft Knowledge Base article ID
Q150930. With Windows NT 3.51, and 4.0 up to service pack 1 the
change is global. Starting with NT 4.0 Service pack 2 the change
can be applied to specific print queues, (see Knowledge Base
article ID Q168457).Under Windows NT 4.0, the change is:Run Registry Editor
(REGEDT32.EXE)From the HKEY_LOCAL_MACHINE subtree, go
to the following key:\SYSTEM\CurrentControlSet\Services\LPDSVC\ParametersOn the Edit menu, click
Add Value.Add the following:Value Name:SimulatePassThroughData Type:REG_DWORDData1The default value is 0, which informs LPD to assign
datatypes according to the control commands.Under Windows NT 3.51, the change is:Run Registry Editor
(REGEDT32.EXE)From the HKEY_LOCAL_MACHINE subtree, go
to the following key:\SYSTEM\CurrentControlSet\Services\LPDSVC\ParametersOn the Edit menu, click
Add Value.Add the following:Value Name:SimulatePassThroughData Type:REG_DWORDData1The default value is 0, which informs LPD to assign
datatypes according to the control commands.Create an LPD key at the same level as the LPDSVC
key.Click the LPDSVC Key, click Save
Key from the Registry menu,
and then save the file as
LPDSVC.KEYClick the LPD key created in step 5.Click Restore on the
Registry menu, click the file created in
step 6, and then click OK.A warning message appears. Click
OK and then quit the Registry
Editor.At a command prompt window, type:net stop lpdsvcnet start lpdsvcPrinting Postscript and DOS command filesOne problem with printing under Win31 and Win95 with the LPR
methods discussed is the lack of a rawLPT1: device. This is annoying to the
administrator who wants to print an occasional text file, such as a
file full of printer control codes, without their being intercepted by
the Windows printer driver. Of course this is also an issue with DOS
programs, but a commercial site that runs significant DOS software and
wants to print directly to UNIX with LPR really only has one
option—to use a commercial TCP/IP stack containing a DOS LPR
program.Normally, under Windows printing, virtually all graphical programs
print through the Windows printer driver. This is true even of basic
programs such as Notepad. For example, an administrator may have a
DOS batch file named filename.txtcontaining the
following line:echo \033&k2G > lpt1:This batch file switches a HP LasterJet from CR-LF, MS-DOS
textfile printing into Newline termination UNIX textfile printing.
Otherwise, raw text printed from UNIX on the HP prints with a
stairstep effect.If the administrator opens this file with Notepad and prints it
using a regular printer driver, such as an Epson LQ, the Windows
printer driver encapsulates this print output into a series of
printer-specific control codes that do things such as initialize the
printer, install fonts, and so on. The printer won't interpret this
output as control code input. Usually, if the printer is locally
attached, the user can force a "raw text print" of the file by opening
a DOS window and running:copy filename.txt lpt1: /bSince the LPR client program doesn't provide a DOS driver, it
cannot reroute input from the LPT1: device
ports. The solution is to use the Generic / Text Only printer driver
in conjunction with Wordpad (under Win95); under Win31 use a different
text editor. The Notepad editor supplied with Windows is unsuitable
for this - it "helpfully" inserts a 1 inch margin of spaces around all
printed output, as well as the filename title. Wordpad supplied with
Win95, can be set to use margins of zero, and inserts no additions
into the printed output. Also, make sure that banner pages are turned
off, and the print type is set to raw.Checking PostScript Printer capabilitiesFollowing is a PostScript command file that can be used to get a
PostScript printer to output a number of useful pieces of information
that are needed to set up a printer icon under Windows properly. It
was printed from Wordpad, in Win95, through the Generic / Text Only
printer driver with the following instructions:Start, Run,
type in Wordpad and press
Enter.File, Opentestps.txtFile, Page
Setup, Printer, select
Generic / Text Only, click
PropertiesClick Device Options, select
TTY custom, click
OK.Click OK, then set all four margins to
0; click OK.Click File,
Print,
OK.This could also have been printed with
/usr/bin/lpr on a UNIX command prompt. The file
prints Test Page and some printer statistics
below that, as follows.% filename: testps.txt
% purpose: to verify proper host connection and function of PostScript
% printers.
/buf 10 string def
/CM {
save statusdict/product get (Postscript) anchorsearch
exch pop {length 0 eq
{1}{2}ifelse
}
{2}ifelse exch restore
}bind def
/isCM {
CM 1 ge
}bind def
/Times-BoldItalic findfont 75 scalefont setfont
150 500 moveto
(Test Page) false charpath
isCM{gsave 0.0 1.0 1.0 0.0 setcmykcolor fill grestore}if
2 setlinewidth stroke
/Times-Roman findfont 10 scalefont setfont
150 400 moveto
(Your PostScript printer is properly connected and operational.)show
150 380 moveto
(The border around the page indicates your printer's printable region.)show
{ vmreclaim } stopped pop
vmstatus exch sub exch pop
150 360 moveto
(Max Available Printer Virtual Memory (KB):)show
150 340 moveto
dup 1024 div truncate buf cvs show
150 320 moveto
(Calculated memory size used for PostScript printer icon properties:) show
150 300 moveto
0.85 mul 1024 div truncate buf cvs show
150 280 moveto
(Printer Model: )show
statusdict begin product show end
150 260 moveto
(PostScript Level: )show
/languagelevel where
{ languagelevel 3 string cvs show pop }
{(1) show } ifelse
150 240 moveto
(PostScript Version: )show
statusdict begin
version show (.)show
revision 40 string cvs show end
clippath stroke
showpageSetting up LPR/LPD on FreeBSDWhen a FreeBSD system is booted, it starts the LPD spooler control
daemon program if the /etc/rc.conf file has
lpd_enable="YES" set. If this is not set, attempts
to print through and from the FreeBSD system will fail with an
lpr: connect: No such file or directory error
message.The LPD program manages all incoming print jobs, whether they come
in from the network, or from local users on the UNIX system. It
transfers print jobs to all locally attached parallel or serial
printers, as well as defined remote printers. Several programs also
are used to manipulate jobs in the print spools that LPD manages, as
well as the user programs to submit them from the UNIX command prompt.
All of these programs use the /etc/printcapfile,
which is the master control file for the printing system.Back when printing was mostly text, it was common to place
printers on a serial connection that stretched for long distances.
Often, 9600bps was used because it could work reliably up to a block
away, which allowed printers to be located almost anywhere on an
office high-rise floor. Modern office print jobs, on the other hand,
are generally graphics-laden and tend to be rather large. These jobs
would take hours to transfer over a slower 9600bps serial printer
connection. Today, most printers that are not connected to a remote
hardware print server box are directly connected to the server using
parallel cables. All of the examples shown here are direct
connections that are parallel connections.The printcap configuration file, like most
UNIX configuration files, indicates comment lines starting with a hash
character. Lines without a hash character are meant to be part of a
printer queue description line. Each printer queue description line
starts with a symbolic name, and ends with a newline. Since the
description lines are often quite long, they are often written to span
multiple lines by escaping intermediate newlines with the backslash
(\) character. The
/etc/printcapfile, as supplied, defines a single
printer queue, lp. The lpqueue
is the default queue. Most UNIX-supplied printing utilities send
print output to this queue if no printer is specified by the user. It
should be set to point to the most popular print queue with
local UNIX print users, (i.e.: users that have
shell accounts).The layout of /etc/printcapis covered in the
manual page, which is reached by running the man
printcap command. The stock
/etc/printcap file at the line defining the spool
lpshows:#
lp|local line printer:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
#In this example the first line defines the names by which the
printer is known, and ends with an escaped newline. The next line
defines the physical device, the PC parallel port, by
/dev/lpt0, and the directory in which the spool
files are stored at /var/spool/output/lpd, and
the error log file. Note that this particular error log file will not
show all LPD errors, such as bad job submittals, it usually shows only
the errors that originate within the printing system itself.In general, the administrator creates two print queues for every
printer that is connected to the FreeBSD machine. The first queue
entry contains whatever additional capabilities UNIX shell users on
the server require. The second is a raw queue that performs no print
processing on the incoming print job. This queue is used by remote
clients, such as Windows clients, that format their own jobs.If the administrator is setting up the printer to allow incoming
LPR jobs from network clients, such as other Windows or UNIX systems,
those systems must be listed in
/etc/hosts.lpd.Creating the spoolsBuilding new print spools is merely a matter of making an entry
in the /etc/printcap file, creating the spool
directories, and setting the correct permissions on them. For
example, the following additional line defines a PostScript printer
named NEC (in addition to the lp
definition):#
lp|local line printer:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
NEC|NEC Silentwriter 95 Postscript printer:\
:lp=/dev/lpt0:sd=/var/spool/output/NEC:lf=/var/log/lpd-errs:
#Because UNIX is case sensitive, NEC is different from
nec in both the name of the printer and the name
of the Spool directory. With the print spooler LPD, the Spool
directories must be different from each other,
or the spooler gets confused and doesen't print.After the /etc/printcapis modified, the
root user must create the /var/spool/output/NEC
directory and assign ownership of it to the bin
user, assign group ownership to daemon, and set
permissions with the following commands:&prompt.user; su root
&prompt.root; cd /var/spool/output
&prompt.root; mkdir NEC
&prompt.root; chown bin NEC
&prompt.root; chgrp daemon NEC
&prompt.root; chmod 755 NECAdditional spool capabilitiesBecause modern print jobs (especially PostScript) can sometimes
reach hundreds of megabytes, the sd capability
entry in the /etc/printcap file should always
point to a Spool directory on a filesystem that has enough space.
The /var directory on a default FreeBSD
installation is generally set to a fairly small amount, which can
easily overflow the spool. There are four ways to handle this
problem:During FreeBSD installation, if the administrator knows a
lot of print jobs are going to go through the spooler,
/varshould be set to a large
amount of free space.Modify the sd capability in the
/etc/printcap file to point to a spool
directory in a different, larger filesystem, such as
/usr/spool.Use soft links to point the
/var/spool/output directory to directories
on a larger filesystem.Don't define a /var directory at all
during FreeBSD installation; this would make the installer link
/var to
/usr/var.In addition to spools, the following other capabilities are
usually placed in a production
/etc/printcapfile.The entry fo prints a form feed when the
printer is opened. It is handy for HPPCL (HP LaserJets) or other
non-PostScript printers that are located behind electronic print
sharing devices. It can also be used for printers that accept input
from multiple connections, such as a parallel port, serial port, and
localtalk port. An example is an HP LaserJet with an MIO card in it
plugged into both Ethernet and LocalTalk networks. It will clear
any garbage out of the printer before the job is processed.The entry mx defines the maximum size of a
print job, which is a must for modern print jobs that frequently
grow far past the default print size of a megabyte. The original
intent of this capability was to prevent errant programs from
stuffing the spool with jobs so large that they would use up all
paper in a printer.. Graphics-heavy print jobs have made it
impossible to depend on this kind of space limitation, so
mx is usually set to zero, which turns it
off.The entry sh suppresses printing of banner
pages in case the printer cannot handle ASCII and the client
mistakenly requests them.The entry ct denotes a TCP Connection
timeout. This is useful if the remote print server doesn't close
the connection properly.FreeBSD 2.2.5 contains a bug in the LPD system - as a
workaround the ct capability needs to be set
very large, such as 3600, or the appropriate patch installed and
LPD recompiled. More recent versions of FreeBSD do not have this
bug.Printing to hardware print server boxes or remote print
servers.Hardware print server boxes, such as the HP JetDirect internal
and external cards, need some additional capabilities defined in the
/etc/printcap entry; rp, for
remote print spool, and rmfor remote machine
name.The rm capability is simply the DNS or
/etc/hosts name of the IP number associated
with the remote printserver device. Obviously, print server
devices, such as the HP JetDirect, must not use a dynamic TCP/IP
network numbering assignment. If they get their numbering via DHCP,
the IP number should be assigned from the static pool; it should
always be the same IP number.Determining the name used for rp, on the
other hand, can be rather difficult. Here are some common
names:Windows NT Server: Printer name of the printer icon created in
Print ManagerFreeBSD: Print queue name defined in
/etc/printcapHP JetDirect: Either the name TEXT or the
name RAW. TEXT automatically
converts incoming UNIX newline text to DOS-like CR/LF text that the
printer can print. RAW should be used for
PostScript, and HPPCL printing.HP JetDirect EX +3: External, 3 port version of the JetDirect.
Use RAW1, RAW2,
RAW3, TEXT1,
TEXT2, or TEXT3 depending on
the port desired.Intel NetPort: Either use TEXT for UNIX text
conversion printing or use PASSTHRU for normal
printing.DPI: Use PORT1 or PORT2
depending on which port the printer is plugged into.For other manufacturer's print servers refer to the manuals
supplied with those devices.The following is an example printcap that redefines the default
lp print queue to send print jobs to the first
parallel port on a remote HP LaserJet plugged into a JetDirect EX +3
named floor2hp4.biggy.com.#
lp|local line printer:\
:rm=floor2hp4.biggy.com:rp=RAW1:\
:sd=/var/spool/output/lpd:\
:lf=/var/log/lpd-errs:
#The rp capability must
be defined or the job goes to the default print queue on the
remote host. If the remote device does not have a single print
queue, such as another UNIX system, this causes problems. For
example, if the remote device was a JetDirect EX + 3 and
rp was omitted, all queues defined would print
out of the first parallel port.FiltersThe last two important printcap capabilities concern print
filters, if (input filter) and
of (output filter) If defined, incoming print
jobs are run through the filters that these entries point to for
further processing.Filters are the reason that the UNIX print spooling system is so
much more powerful than any other commercial server operating
system. Under FreeBSD, incoming print jobs are acted on by any
filters specified in the /etc/printcapno matter where they originate. Incoming print
jobs from remote Windows, Mac, NT, OS/2 or other clients can be
intercepted and manipulated by any program specified as a filter.
Want a PostScript Printer? There's a filter that adds PostScript
capability to a non-PostScript printer. Want to make a cheap Epson
MX 80 dot-matrix emulate an expensive Okidata Microline dot-matrix
for some archaic mainframe application? Write a filter that will
rewrite the print codes to do it. Want custom-built banner pages?
Use a filter. Many UNIX /etc/printcap filters
on many Internet sites can do a variety of interesting and unique
things. Someone may have already written a filter that does what you
want!Types of filtersThree types of filters can be defined in the
/etc/printcap file. In this book all filter
examples are for Input filters.Input FiltersInput filters are specified by the if
capability. Every job that comes into the spool is acted on by
any filter specified in the if entry for that
spool. Virtually all filters that an administrator would use are
specified here. These filters can be either shell scripts, or
compiled programs.Fixed FiltersFixed filters are specified by separate capabilities, such
as cf, df, and
gf. Mostly, these exist for historical
reasons. Originally, the idea of LPD was that incoming jobs
would be submitted with the type fields set to trigger whatever
filter was desired. However, type codes are confusing and
annoying to the user, who has to remember which option is needed
to trigger which type. It is much easier to set up multiple
queues with different names, and this is what most sites do
these days. For example, originally a DVI fixed filter might be
specified in a spool for lp, triggered by the
option passed to lpr.
Jobs without this option aren't acted on by the DVI filter.
However, the same thing can be done by creating a queue named
lp that doesn't have a DVI filter, and a
queue named lpdvi which has the DVI filter
specified in the if capability. Users just
need to remember which queue to print to, instead of what option
needed for this or that program.Output FiltersThese are specified by the ofcapability.
Output filters are much more complicated than input filters and
are hardly ever used in normal circumstances. They also
generally require a compiled program somewhere, either directly
specified or wrapped in a shell script, since they have to do
their own signal-handling.Printing raw Unix text with a filterOne of the first thing that a new Unix user will discover when
plugging a standard LaserJet or impact printer into a UNIX system
is the stairstep problem. The symptom is
that the user dumps text to the printer, either through LPR or
redirection (by catting it to the parallel device) and instead of
receiving the expected Courier 10-point printout, gets a page with
a single line of text, or two lines of text "stairstepped", text
and nothing else.The problem is rooted in how printers and UNIX handle
textfiles internally. Printers by and large follow the "MS-DOS
Textfile" convention of requiring a carriage return, then a
linefeed, at the end of every text line. This is a holdover from
the early days when printers were mechanical devices, and the
print head needed to return and the platen to advance to start a
new line. UNIX uses only the linefeed character to terminate a
text line. So, simply dumping raw text out the parallel port
works on MS-DOS, but not on UNIX.If the printer is a PostScript printer, and doesn't support
standard ASCII, then dumping UNIX text to it doesn't work. But
then, neither would dumping MS-DOS text to it. (Raw text printing
on PostScript printers is discussed later in this chapter) Note
also that if the printer is connected over the network to an HP
JetDirect hardware print server, internal or external, the TEXT
queue on the hardware print automatically adds the extra Carriage
Return character to the end of a text line.If the printer is the garden-variety HP LaserJet, DeskJet, or
an impact printer, and under DOS the administrator is used to
printing raw text from the command line for directory listings,
there are two ways to fix stairstep. The first is to send a
command to the printer to make it print in "unix textfile" mode,
which makes the printer supply it's own carriage return. This
solution is ugly in a printer environment with UNIX and Windows
machines attempting to share use of the same printer. Switching
the printer to work with Unix disrupts DOS/Windows raw text
printouts.The better solution is to use a simple filter that converts
incoming text from UNIX style to DOS style. The following filter
- posted on questions@freebsd.org and the sample
+ posted on questions@FreeBSD.org and the sample
/etc/printcap entry can be used to do
this:#!/bin/sh
# /usr/local/libexec/crlfilter
#
# simple parlor trick to add CR to LF for printer
# Every line of standard input is printed with CRLF
# attached.
#
awk '{printf "%s\r\n", $0}' -An alternative filter posted using sed could be written
as:#!/bin/sh
# /usr/local/libexec/crlfilter
#
# Add CR to LF for printer
# Every line of standard input is printed with CRLF
# attached.
#
# Note, the ^M is a *real* ^M (^V^M if your typing in vi)
#
sed 's/$/^M/' -Here is an example of a filter that triggers the printers
automatic LF-to-CR/LF converter (this option is only useful on HP
LaserJets that support this command):#!/bin/sh
# Simply copies stdin to stdout. Ignores all filter
# arguments.
# Tells printer to treat LF as CR+LF. Writes a form feed
# character after printing job.
printf "\033&k2G" && cat && printf "\f" && exit 0
exit 2The printcap file used to trigger the filter is:#/etc/printcap
# The trailer (tr) is used when the queue empties. I found that the
# form feed (\f) was basically required for the HP to print properly.
# Banners also need to be shut off.
#
lp|local line printer:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
:if=/usr/local/libexec/crlfilter:sh:tr=\f:mx#0:
#The pr filterAlthough most filters are built by scripts or programs and are
added to the UNIX machine by the administrator, there is one
filter that is supplied with the FreeBSD operating system is very
useful for raw text files: the prfilter. It is
most commonly used when printing from the UNIX command shell. The
pr filter paginates and applies headers and
footers to ASCII text files. It is automatically invoked with the
option used with the lpr
program at the UNIX command prompt.The pr filter is special - it runs in
addition to any input filters specified for the print
queue in /etc/printcap,
if the user sets the option for a print job.
This allows headers and pagination to be applied in addition to
any special conversion, such as CR to LF that a specified input
filter may apply.Printing PostScript banner pages with a Filter.Unfortunately, the canned banner page supplied in the LPD
program prints only on a text-compatible printer. If the attached
printer understands only PostScript and the administrator wants to
print banner pages, it is possible to install a filterinto the
/etc/printcapfile to do this.The following filter is taken from the FreeBSD Handbook. I've
slightly changed it's invocation for a couple of reasons. First,
some PostScript printers have difficulty when two print files are
sent within the same print job or they lack the trailing
Control-D. Second is that the handbook invocation uses the LPRPS
program, which requires a serial connection to the printer.The following filter shows another trick: calling LPR from
within a filter program to spin off another print job.
Unfortunately, the problem with using this trick is that the
banner page always gets printed after the job. This is because
the incoming job spools first, and then FreeBSD runs the filter
against it, so the banner page generated by the filter always
spools behind the existing job.There are two scripts, both should be put in the
/usr/local/libexec directory, and the modes
set to executable. The printcap also must be
modified to create the nonbanner and banner versions of the print
queue. Following the scripts is the
/etc/printcap file showing how they are
called. Notice that the sh parameter is turned
on since the actual printed banner is being generated on the fly
by the filter:#!/bin/sh
# Filename /usr/local/libexec/psbanner
# parameter spacing comes from if= filter call template of:
# if -c -w -l -i -n login -h host
# parsing trickiness is to allow for the presence or absence of -c
# sleep is in there for ickiness of some PostScript printers
for dummy
do
case "$1" in
-n) alogname="$2" ;;
-h) ahostname="$2" ;;
esac
shift
done
/usr/local/libexec/make-ps-header $alogname $ahostname "PostScript" | \
lpr -P lpnobanner
sleep 10
cat && exit 0Here is the make-ps-headerlisting.#!/bin/sh
# Filename /usr/local/libexec/make-ps-header
#
# These are PostScript units (72 to the inch). Modify for A4 or
# whatever size paper you are using:
#
page_width=612
page_height=792
border=72
#
# Save these, mostly for readability in the PostScript, below.
#
user=$1
host=$2
job=$3
date=`date`
#
# Send the PostScript code to stdout.
#
exec cat <<EOF
%!PS
%
% Make sure we do not interfere with user's job that will follow
%
%
% Make a thick, unpleasant border around the edge of the paper.
%
$border $border moveto
$page_width $border 2 mul sub 0 rlineto
0 $page_height $border 2 mul sub rlineto
currentscreen 3 -1 roll pop 100 3 1 roll setscreen
$border 2 mul $page_width sub 0 rlineto closepath
0.8 setgray 10 setlinewidth stroke 0 setgray
%
% Display user's login name, nice and large and prominent
%
/Helvetica-Bold findfont 64 scalefont setfont
$page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto
($user) show
%
% Now show the boring particulars
%
/Helvetica findfont 14 scalefont setfont
/y 200 def
[ (Job:) (Host:) (Date:) ] {
200 y moveto show /y y 18 sub def
} forall
/Helvetica-Bold findfont 14 scalefont setfont
/y 200 def
[ ($job) ($host) ($date) ] {
270 y moveto show /y y 18 sub def
} forall
%
% That is it
%
showpageHere is the /etc/printcap file.#
lp|local line printer, PostScript, banner:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
:if=/usr/local/libexec/psbanner:sh:mx#0:
lpnobanner|local line printer, PostScript, no banner:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd-noban:\
:lf=/var/log/lpd-errs:sh:mx#0:
#Printer AccountingThe FreeBSD print spooler can manage accounting statistics for
printer usage. The spooler counts each page printed and generates
totals for each user. In this manner departments or individuals can
be charged money for their use of the printer.In the academic world, such as student computer labs, accounting
is very political. Many schemes have been developed to attempt to
gather statistics to charge people (generally students) for printing.
Administrators in this environment who deal with printers can have
almost as many accounting problems as printer problems. In the
corporate environment, on the other hand, accounting is not as
important. I strongly recommend against any corporation attempting to
implement printer accounting on shared printers for a number of
reasons:The entire UNIX accounting system is based on ASCII printouts.
It is easy to count the number of ASCII pages, form feeds, or text
lines in a print job. In corporations, however, PostScript and
HPPCL are generally the order of the day. It is almost impossible
to figure out by examining the datastream how many pages it will
occupy, and even if this could be done accurately, it wastes
significant computational resources.It is possible to get some PostScript printers to count
pages, but doing so requires a bidirectional connection to the
printer and additional programming on the UNIX system. This
task is beyond the scope of this book.Banner pages aren't included in UNIX printer accounting
counts. Therefore, someone submitting 20 two-page jobs uses much
more paper than does someone submitting one 40 page job, yet both
are charged the same amount.The username of the submitter can be easily forged, if the job
is remotely submitted over the network from a client. (practically
all jobs in a Windows client printing environment are remotely
submitted) Although some LPR clients can be set to authenticate,
and the rs capability can be set to enforce
authentication, not all can, especially Windows LPR
clients.It is more difficult for a submitter to hide the IP number or
machine name of the remote client, but in a Windows environment
there is no guarantee that someone was sitting at a particular
desktop machine when the job was submitted.A business generates no revenue by monitoring printer usage.
In the academic community, however, when a student lab charges for
printouts the lab is actually extracting money from an entity (the
student) that is separate from the lab. Within a corporation, the
concept of department A getting revenue from user B is pointless
and doesn't generate a net gain for the corporation as a
whole.For my printer administration, I have found that I can save
more money on printing costs by purchasing supplies wisely than by
attempting to discourage printing through "chargebacks". What is
the sense of being miserly with printing while spending double on
toner cartridges because no one is willing to comparison shop, or
signing a "lease" agreement that isn't beneficial for the printer?
When you get down to it, corporate users don't care much for print
sharing anyway, and they generally only agree to it because the
administrator can buy a far bigger, faster, and fancier printer
than they can requisition.Worse yet, if usage on a shared printer is charged, it
encourages employees to look for other places to print.
Inevitably, people run out buy cheap inkjet printers for their own
use, and the business ends up spending more on paper and supplies
for many poor-quality small printers, than it would for a few
decent big ones. Moreover, the inferior output of these printers
makes the organization as a whole look bad.The corporate spirit should be one of teamwork, not bickering.
The surest way to kill a network in a corporation is to set up a
situation that puts the administrator into the policeman position
or pits one department against another.The only justification I've ever seen for running accounting on
corporate printers is using the accounting system to automate
reminders to the administrator to replace paper, or toner. Aside from
this use, a corporation that implements accounting as a way of
encouraging employees not to waste paper ends up defeating the purpose
of turning on accounting.Microsoft Networking Client printing with SambaAlthough LPR is a time-tested and truly cross-platform printing
solution, sites with a majority of Windows clients running Microsoft
Networking have an alternate printing mechanism—Samba. Samba
can provide print services to clients running SMB-compatible network
clients. With a running Samba installation, the administrator may
"share out" printers as well as filesystem directories from the
FreeBSD system.Printers accessed with Samba must be defined both in the
/etc/printcap file and the
/usr/local/etc/smb.conf file. If the individual
printers are defined in the smb.conf file with
the printer driver= statement set to the exact
model name of the printer, the "Auto printer driver install" feature
of Windows NT and Win95/98 is activated. This automatically loads the
correct printer driver if the user clicks on the print queue in
Network Neighborhood under Windows 95 or NT 4.0 The restriction, of
course, is that the printer model must be in the Windows client driver
database.The smb.conf file also defines the
print command used to pass jobs to the UNIX print
spool. It is a good idea to redefine this via the print
command option to lpr -s -P %p %s; rm
%s. This turns on soft linking, so that large print jobs
don't get truncated.In operation, the SMB-networking client builds the print job on
itself and then transfers the entire job over the network to the Samba
server. On the server, Samba has it's own temporary print spool
directory to which the job is copied. Once the job has been
completely received, it is then passed to the UNIX print
spooler.Microsoft Networking Client printing with Samba ,---------.
| ======= | FreeBSD Server
| ======= | +---------------------+ ,-----.
+-----------+ | +---------------+ | | |
| Printer [ ]------------[ ] | Samba | | |_____|
+-----------+ Parallel | | Software | [ ]------_________
Cable | +---------------+ | / ::::::: \
| | `---------'
| +---------------+ | Network PC
| | Print | |
| | Software | |
| +---------------+ |
+---------------------+The Samba software and the print software run on the same
host. Samba receives the print job, then hands it to the print
spooler.Client access issuesBecause a Windows client formats print jobs before sending them
to the server, the administrator may want to hide some of the
specialty print queues on the server. For example, the queue that
converts LF to CRLF for UNIX text printouts would probably not be
shared out. To make such queues invisible, the
browseable=no option can be turned on in the
smb.conf file. Also, the load
printers option must be set to no to allow individual
printer definitions.In general, the only print queues that should be visible
through Samba are the "raw" print queues that are set up by the
administrator to allow incoming preformatted print jobs.Windows clients that print to Samba print queues on the UNIX
system can view and cancel print jobs in the print queue. They
cannot pause them, however, which is a difference between Novell and
Windows NT Server print queues. They also cannot prioritize print
jobs from the print queue window, although the administrator can
reprioritize print jobs that are in the queue from a command shell
on the FreeBSD server.Printer entries in configuration filesFollowing are listings of sample
/etc/printcap file, and
smb.conf files used on the system to provide
print services. An explanation of the interaction of these files
follows./etc/printcap#
#
# The printer in lpt0 is a Postscript printer. The nec-crlf entry
# is for testing the printer when it is switched into HP LaserJet III
# mode.
#
lp|local line printer:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:\
:lf=/var/log/lpd-errs:sh:mx#0:
#
nec-crlf|NEC Silentwriter 95 in ASCII mode with Unix text filter:\
:lp=/dev/lpt0:sd=/usr/lpdspool/nec-crlf:\
:lf=/var/log/lpd-errs:sh:mx#0:\
:if=/usr/local/libexec/crlfilter:tr=\f:
#
nec-raw|NEC Silentwriter 95 used for PostScript passthrough printing:\
:lp=/dev/lpt0:sd=/usr/lpdspool/nec-raw:\
:lf=/var/log/lpd-errs:sh:mx#0:
#
nec-ps-banner|NEC Silentwriter 95 with Postscript banner page created:\
:lp=/dev/lpt0:sd=/usr/lpdspool/nec-ps-banner:\
:lf=/var/log/lpd-errs:sh:mx#0:if=/usr/local/libexec/psbanner:
#
#/usr/local/etc/smb.conf[global]
comment = FreeBSD - Samba %v
log file = /var/log/samba.log
dont descend = /dev,/proc,/root,/stand
print command = lpr -s -P %p %s; rm %s
interfaces = X.X.X.X (the system IP number goes here)
printing = bsd
map archive = no
status = yes
public = yes
read only = no
preserve case = yes
strip dot = yes
security = share
guest ok = no
password level = 1
dead time = 15
domain master = yes
workgroup = WORKGROUP
[homes]
browseable = no
comment = User Home Directory
create mode = 0775
public = no
[printers]
path = /var/spool
comment = Printers
create mode = 0700
browseable = no
read only = yes
public = no
[lp]
printable = yes
browseable = no
[nec-raw]
comment = Main Postscript printer driver for Windows clients
printer driver = NEC SilentWriter 95
printable = yes
browseable = yes
[wwwroot]
path = /usr/local/www
read only = no
create mode = 0775
comment = Internal Web ServerBrowsing outputFollowing is the output of a net view
command executed at a DOS prompt under Windows 95:Shared resources at \\SERVER
Sharename Type Comment
--------------------------------------------------------------------
nec-crlf Print NEC Silentwriter 95 in ASCII mode
nec-raw Print Main Postscript printer driver
tedm Disk User Home Directory
wwwroot Disk Internal Web Server
The command was completed successfully.In the /etc/printcap file four print queues
are defined, all tied to the printer plugged into the parallel port
on the FreeBSD server. The first is lp, the
generic local line printer. Since this print queue generally has a
filter placed on it to format jobs from the UNIX print queue
properly, it should not be visible on the SMB network. (ie: visible
in Network Neighborhood) The second queue,
nec-crlf, has a filter that converts UNIX text to
text that prints without stairstepping, so it also should be hidden
from the SMB network. The third, nec-raw, should
be visible on the network because this is the spool that the Windows
clients use. The last queue, nec-ps-banner, is
another specialty queue for UNIX local printing and thus should not
be visible.When the smb.conf file is parsed, the
default entry [printers] is first read and used
as a set of defaults for printers that are going to be shared out.
Next, the /etc/printcap file is read to get a
list of all printers on the server. Last, each printer is checked
for a service name in the smb.conffile that
contains settings that override the set of defaults.In the listing of what resources are visible on the network,
both nec-crlf and nec-raw
print queues are visible, and lpand
nec-ps-banner is not. lp is
not visible because there is a specific entry,
[lp] in the smb.conf file
that blocks it. nec-ps-banner doesen't have such
an entry, but because the print queue name is not a legal length for
a SMB name, it isn't shared out either.The nec-crlf printer is visible so as to
illustrate another point - comments. If a print queue has no entry
in the smb.conf file and is built by scanning
the /etc/printcap file and using the
[printers] defaults, the comment is taken from
the /etc/printcap file next to the queue
definition name. Otherwise, if an entry is made for the printer in
the smb.conf file the comment is taken from the
entry in smb.conf.Printing between NT Server/NetWare and FreeBSD.Up to this point in the chapter, our main concern has been FreeBSD
and Windows NT printing interoperability with NT as a print client
passing jobs to the FreeBSD system. What happens if the situation is
reversed and the FreeBSD system is itself a printing client of another
LPD server? This situation can arise in a mixed UNIX/Netware or
UNIX/NT environment. The administrator may elect to forgo the use of
Samba, and use an NT server to provide print services. Alternatively,
the administrator may have existing DOS Novell IPX clients that they
don't want to change, printing to an existing IPX Novell NetWare
server. Many of the earlier hardware print servers, such as the Intel
NetPort 1 and NetPort 2 were IPX only. A site with a large number of
these hardware servers may wish to move the clients to TCP/IP, but
leave the existing IPX-based printing network intact.With NetWare it is possible to load an LPD NetWare loadable module
(NLM) on the NetWare server that takes incoming LPR print jobs and
prints them on IPX print queues. Later versions of NetWare may
include this NLM, it was an extra cost add-on with NetWare 3.XWith Windows NT Server, loading the TCP/IP LPR printing support
also loads the LPD print server on NT. By using LPR client programs
on UNIX, it is possible to submit, view status, and remove jobs
remotely from an NT server that has LPR installed as a port for it's
printers.Following is a sample /etc/printcapfile entry
that defines a print queue named tankon the FreeBSD
system pointed to an NT LPD server queue named
sherman on a NT Server named
big.army.mil in the DNS. This uses the
rm printcap capability. Unlike the earlier
examples, the output print jobs are sent out not by the PC parallel
port but over the network to the NT server.#
tank|sample remote printer:\
:rm=big.army.mil:rp=sherman:sd=/var/spool/output/lphost:\
:lf=/var/log/lpd-errs:
#When using an NT server as an LPD server it may be necessary to
make the NT registry changes mentioned under Windows NT Registry
Changes, earlier in the chapter.Printing from UnixTwo commands used at the FreeBSD command prompt are intended as
general-purpose print commands: lp and
lpr..lpThe lp command is simply a front end command
that calls the lpr command with appropriate
options. It's main use is to allow the running of precompiled
binary programs and scripts that assume that the
lp command is the official
printing command.lprThe lpr command is the main command that is
used to print files from the command prompts under the FreeBSD
operating system. It is frequently spawned off as a child program,
or used in pipes. For example, when the Netscape web browser's
Print button is clicked, Netscape may create the PostScript output,
but the output goes through the lpr
command.The lpr command, like many UNIX command-line
printing programs, assumes that the default print queue name is
lp. When the FreeBSD machine is set up, the
administrator usually sets the lp queue to print
through a filter that allows raw UNIX text sent to it to print
properly. For example, if an HP LaserJet printer that doesn't have
Postscript is connected to the server, the
lpqueue specifies in the
/etc/printcap file the CRLF filter listed
earlier. On the other hand, if an Apple Laserwriter that doesn't
support ASCII is connected to the server, the
a2psfilter would be specified in the
/etc/printcap for the lp
queue.When printing raw text files usually the
option is specified to lpr. When printing
preformatted files, such as PostScript files, the
option is used, which selects whatever queue is
used to handle these job types.Managing the Unix Print QueueOnce the print jobs coming in from clients are received on the
FreeBSD system and placed in the print spool, they are metered out
at a slower rate to the various printers. If traffic activity is
light, and few print jobs get sent through, the administrator can
probably ignore the print queue as long as it continues to work.
However, a busy network printer running at an optimal rate of speed
usually has a backlog of unprinted jobs in the queue waiting for
print time. To keep all users happy and to provide for the
occasional rush print job, the Unix LPD/LPR printing system has
several administration commands which are described here.Viewing the queueOn busy printers, and to troubleshoot stopped printers, users
sometimes need to view the print jobs in the queue. Administrators
also need to view the queue to see what jobs may need to be
expedited. This can be done from the workstation that remotely
submitted the job if the LPR client has the ability to do this.
The Windows 3.1 LPR client discussed earlier has this capability.
Unfortunately, many LPR clients don't, which means that the
administrator must Telnet into the UNIX machine that the print
queues are on and view them there.The UNIX shell command used to view the queue is the
lpq command It is frequently run as
lpq -a which shows jobs in all queues. The
following is a sample output of the command:&prompt.root; lpq -a
nec-raw:
Rank Owner Job Files Total Size
1st tedm 19 C:/WLPRSPL/SPOOL/~LP00018.TMP 105221 bytes
2nd tedm 20 C:/WLPRSPL/SPOOL/~LP00019.TMP 13488 bytes
3rd root 3 hosts 1220 bytes
4th tedm 1 Printer Test Page 765 bytes
5th tedm 2 Microsoft Word - CHAPTE10.DOC 15411 bytesThe first two jobs and the last two jobs came from remote
clients, the third came from the command prompt.Removing print jobsDeleting unwanted print jobs that haven't yet printed from the
queue can be done by the remote workstations that submitted the
job if their LPR implementations have the necessary commands. The
Windows 3.1 LPR client I detailed earlier this capability. Many
LPR clients don't, however, which means that the administrator
must Telnet into the UNIX machine that the print queues are on and
delete the jobs there.The administrator can delete any print jobs from any queues by
running the lprm command followed by the
specified print queue and the job number. Below is a sample
output of the command:&prompt.root; lprm -P nec-raw 19
dfA019tedmitte dequeued
cfA019dostest dequeued
&prompt.root; lprm -P nec-raw 3
dfA003toybox.placo.com dequeued
cfA003toybox.placo.com dequeuedThe lprm command is also used under UNIX to
delete remote print jobs.Advanced managementThe administrator logged into the FreeBSD system as the root
user can also perform several other operations that ordinary users
cannot. These include turning the queues on and off, and moving
print jobs within the print queues. The command used to do this
is the lpc command.lpc has two modes of operation. In the
first mode, the command is run by itself, which puts the
administrator into an lpc prompt. Some general
help is available for the commands, such as the following sample
output:&prompt.root; lpclpc>help
Commands may be abbreviated.
Commands are:
abort enable disable help restart status topq ?
clean exit down quit start stop up
lpc>help disable
disable turn a spooling queue off
lpc>help status
status show status of daemon and queue
lpc>exitIn the second mode of operation the lpc
command is just run by itself, followed by the command and the
print queue name. Following is a sample output:&prompt.root; lpc disable lp
lp:
queuing disabledUnder FreeBSD, there is no command that specifically allows
the administrator to move jobs from one queue to another. This
can be done, however, by changing into the raw queue directory
then rerunning the lpr command. Following is a
sample run showing three print jobs moved from a dysfunctional
queue to a good one:&prompt.root; lpq -a
lp:
Warning: lp is down: printing disabled
printing disabled
Rank Owner Job Files Total Size
1st root 51 hosts 1220 bytes
2nd root 52 services 60767 bytes
3rd root 53 printcap 2383 bytes
&prompt.root; cd /var/spool/output/lpd
&prompt.root; ls
.seq cfA053toybox.placo.com dfA053toybox.placo.com
cfA051toybox.placo.com dfA051toybox.placo.com lock
cfA052toybox.placo.com dfA052toybox.placo.com status
&prompt.root; lpr -P nec-raw dfA051toybox.placo.com
&prompt.root; lpr -P nec-raw dfA052toybox.placo.com
&prompt.root; lpr -P nec-raw dfA053toybox.placo.com
&prompt.root; lprm -P lp -
&prompt.root; lpq -a
nec-raw:
Warning: nec-raw is down: printing disabled
Warning: no daemon present
Rank Owner Job Files Total Size
1st root 5 dfA051toybox.placo.com 1220 bytes
2nd root 6 dfA052toybox.placo.com 60767 bytes
3rd root 7 dfA053toybox.placo.com 2383 bytesMoving jobs from queue to queue is feasible only when all
printers are similar, as when all printers support
PostScript.Remote ManagementJust as the root user can manipulate remotely submitted jobs
in the print queue, print jobs can be remotely managed by regular
users with the LPR clients that created them. Unfortunately, some
LPR clients, such as Win95, don't have enough programming to be
able to do this. Others, like the Win31 client, can manipulate
the print jobs remotely.FreeBSD offers some level of protection against inadvertent
deletion of print jobs from remote hosts by restricting
manipulation of a job to the same host that originated it. Even
if the owner of the job matches a local user account on the
server, for an ordinary user to delete remotely submitted print
jobs, the request still must come from the remote host.Advanced Printing TopicsThe FreeBSD UNIX LPR/LPD printing system is very flexible, and,
with the addition of filters, can be adapted to very unusual printing
environments. To enhance this flexibility, several useful printing
utilities are supplied on the FreeBSD CDROM which the administrator
might wish to install.GhostscriptThe Ghostscript program, invoked as
/usr/local/bin/gs, is one of the most useful
printing utilities that have been developed for the free software
community. Ghostscript reads incoming PostScript data, (or Adobe
PDF files) interprets it, and outputs it as a raster image. This
can be displayed on screen, for example, with the GhostView program
under the X Window system, or printed on most graphics printers,
such as Epson dot-matrix, HP DeskJet, or HP LaserJet. In effect, it
is a way of adding PostScript printing capability to a printer that
doesn't have PostScript firmware code. Ghostscript has been ported
to numerous operating systems including Windows.The Ghostscript home page is located at
http://www.cs.wisc.edu/~ghost/
and contains the most current version of the program. A prebuilt
FreeBSD binary of Ghostscript located in the Packages section of the
FreeBSD CDROM. This can be installed on the FreeBSD system by
selecting the package from the prepackaged software list that is
accessed through the /stand/sysinstall
installation program. Many packaged programs on the CD depend on
GhostScript, and so it may already be installed.Installation of the packaged version of GhostScript is
recommended in the FreeBSD ports Section because it has been tested
with the other packages that require it. The package creates a
directory containing some documentation files in
/usr/local/share/ghostscript/X.XX/doc.
Unfortunately, because of the packaging process on the FreeBSD CDROM
not all the useful installation files are copied into this location.
So, if the package was version 5.03 (for example) the administrator
will also want to get the file
ftp://ftp.cs.wisc.edu/ghost/aladdin/gs503/ghostscript-5.03.tar.gz,
and unzip and untar it into a temporary directory.Extracting the archive file creates a directory structure under
the gs5.03 subdirectory. To install
ghostscript in the /etc/printcap file, read the
gs5.03/devs.mak file to determine which printer
driver definition works with your printer and then use the following
instructions:Change to the root user with su.In the gs5.03directory, copy the
lprsetup.sh,
unix-lpr.txt, and
unix-lpr.sh files to
/usr/local/share/ghostscript/5.03Change to the
/usr/local/share/ghostscript/5.03
directory. Edit lprsetup.sh with a text
editor such as vi.Modify the DEVICES= entries
to list your selected printer driver definitions per the
instructions in unix-lpr.txt.Modify the PRINTERDEV= to
/dev/lpt0, and the GSDIR=
to /usr/local/share/ghostscript, and the
SPOOLDIR= to
/var/spool/output. Save the file.Edit the unix-lpr.sh file and change
the PSFILTERPATH= to
/usr/local/share/ghostscript.If the printer that you defined in the
lprsetup.sh file is a monochrome printer,
remove the "-dBitsPerPixel=${bpp}"and
"$colorspec" entries on the
gs invocation line and save the file.
Otherwise, if it is a color definition leave them in. For
example, the following line is for a monochrome LaserJet:") | gs -q -dNOPAUSE -sDEVICE=${device} \"Don't remove anything else. Exit the editor, and save the
unix-lpr.sh file.Copy the unix-lpr.sh file to the parent
directory, /usr/local/share/ghostscript and
set the execute bit on it.Set the execute bit on lprsetup.sh with
chmod and run the file by typing
./lprsetup.shFollow the instructions on creating the Spool directories.
If you will be using accounting and a separate log file, run the
touch command to create the empty files per
directions in script output.The sample /etc/printcap is located in
the current directory; the filename is
printcap.insert. Use this as a template to
modify the /etc/printcap file. A sample
/etc/printcap file for a LaserJet 3 is
below:#
#
ljet3.raw|Raw output device ljet3 for Ghostscript:\
:rm=big.army.mil:rp=sherman:sd=/var/spool/output/ljet3/raw:\
:mx#0:sf:sh:rs:
#
ljet3|Ghostscript device ljet3 (output to ljet3.raw):\
:lp=/dev/null:sd=/var/spool/output/ljet3:\
:lf=/var/log/lpd-errs:mx#0:sf:sh:rs:\
:if=/usr/local/share/ghostscript/filt/indirect/ljet3/gsif:\
:af=/var/spool/output/ljet3/acct:
#a2ps filterAnother handy utility is the a2ps, short for
ASCII-to-PostScript. This program takes an incoming ASCII
datastream and converts it into PostScript. It can also print
multiple pages on a single sheet of paper by shrinking them down. It
is a useful tool for a printer that cannot interpret ASCII, such as
a PostScript-only printer.A2ps is not installed in the FreeBSD system
by default; it is located in the ports section
/usr/ports/print/a2ps43. A prepackaged binary
can be installed with /stand/sysinstall but I
have had problems with that port. It is best to install it by
running make in the a2ps43 ports directory. A
printcap entry and filter using this follow:/etc/printcap#
lp|local line printer with output dumped through a2ps for raw listings:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:sh:mx#0:\
:if=/usr/local/libexec/ascii2postscript:
#/usr/local/libexec/ascii2postscript#!/bin/sh
#
# Simple filter that converts ASCII to Postscript for basic stuff like
# directory listings.
#
/usr/local/bin/a2ps && exit 0
exit 2Read the system manual page for a2ps to see
the options available with this program, and remember to set the
filter script ascii2postscript
all-executable.MiscellaneousThe large number of other printing utilities cannot be covered
here. Some add features such as automatic job type sensing, others
handle bidirectional communication between the server and the printer.
There are also a few other experimental LPR printing replacement
systems. Commands such as ghostscript and a2ps can
also be used in pipes that create pretty output on an ordinary impact
printer.One last hint - the system manual pages can be printed with the
option which turns their ordinary ASCII output to
beautifully formatted PostScript. Try the command man -t
man and send the output through GhostScript or a
PostScript printer for easier to read manual pages.
diff --git a/en_US.ISO8859-1/books/developers-handbook/book.sgml b/en_US.ISO8859-1/books/developers-handbook/book.sgml
index 880ca4c6ca..ccca2c6086 100644
--- a/en_US.ISO8859-1/books/developers-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/book.sgml
@@ -1,313 +1,313 @@
%bookinfo;
%man;
%chapters;
%authors
%mailing-lists;
]>
FreeBSD Developers' HandbookThe FreeBSD Documentation ProjectAugust 200020002001The FreeBSD Documentation Project
&bookinfo.legalnotice;
Welcome to the Developers' Handbook. This manual is a
work in progress and is the work of many
individuals. Many sections do not yet exist and some of those
that do exist need to be updated. If you are interested in
helping with this project, send email to the &a.doc;.The latest version of this document is always available
- from the FreeBSD World
+ from the FreeBSD World
Wide Web server. It may also be downloaded in a
variety of formats and compression options from the FreeBSD FTP
+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP
server or one of the numerous mirror
+ url="../handbook/mirrors-ftp.html">mirror
sites.Basics
&chap.introduction;
&chap.tools;
&chap.secure;
&chap.l10n;
&chap.policies;
Interprocess Communication* SignalsSignals, pipes, semaphores, message queues, shared memory,
ports, sockets, doors
&chap.sockets;
&chap.ipv6;
Kernel* History of the Unix KernelSome history of the Unix/BSD kernel, system calls, how do
processes work, blocking, scheduling, threads (kernel),
context switching, signals, interrupts, modules, etc.
&chap.locking;
&chap.kobj;
&chap.sysinit;
&chap.vm;
&chap.dma;
&chap.kerneldebug;
* UFSUFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling,
locking, metadata, soft-updates, LFS, portalfs, procfs,
vnodes, memory sharing, memory objects, TLBs, caching* AFSAFS, NFS, SANs etc]* SysconsSyscons, tty, PCVT, serial console, screen savers,
etc* Compatibility Layers* LinuxLinux, SVR4, etcDevice Drivers
&chap.driverbasics;
&chap.isa;
&chap.pci;
&chap.scsi;
&chap.usb;
* NewBusThis chapter will talk about the FreeBSD NewBus
architecture.* Sound subsystemOSS, waveforms, etcArchitectures
&chap.x86;
* AlphaTalk about the architectural specifics of
FreeBSD/alpha.Explanation of allignment errors, how to fix, how to
ignore.Example assembly language code for FreeBSD/alpha.* IA-64Talk about the architectural specifics of
FreeBSD/ia64.AppendicesDaveAPattersonJohnLHennessy1998Morgan Kaufmann Publishers,
Inc.1-55860-428-6Morgan Kaufmann Publishers, Inc.Computer Organization and DesignThe Hardware / Software Interface1-2W.RichardStevens1993Addison Wesley Longman,
Inc.0-201-56317-7Addison Wesley Longman, Inc.Advanced Programming in the Unix Environment1-2MarshallKirkMcKusickKeithBosticMichaelJKarelsJohnSQuarterman1996Addison-Wesley Publishing Company,
Inc.0-201-54979-4Addison-Wesley Publishing Company, Inc.The Design and Implementation of the 4.4 BSD Operating System1-2AlephOnePhrack 49; "Smashing the Stack for Fun and Profit"ChrispinCowanCaltonPuDaveMaierStackGuard; Automatic Adaptive Detection and Prevention of
Buffer-Overflow AttacksToddMillerTheode Raadtstrlcpy and strlcat -- consistent, safe string copy and
concatenation.
&chap.index;
diff --git a/en_US.ISO8859-1/books/developers-handbook/driverbasics/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/driverbasics/chapter.sgml
index a65ec54238..e73fa17cc3 100644
--- a/en_US.ISO8859-1/books/developers-handbook/driverbasics/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/driverbasics/chapter.sgml
@@ -1,391 +1,391 @@
Writing FreeBSD Device DriversThis chapter was written by &a.murray; with selections from a
variety of sources including the intro(4) man page by
&a.joerg;.IntroductionThis chapter provides a brief introduction to writing device
drivers for FreeBSD. A device in this context is a term used
mostly for hardware-related stuff that belongs to the system,
like disks, printers, or a graphics display with its keyboard.
A device driver is the software component of the operating
system that controls a specific device. There are also
so-called pseudo-devices where a device driver emulates the
behaviour of a device in software without any particular
underlying hardware. Device drivers can be compiled into the
system statically or loaded on demand through the dynamic kernel
linker facility `kld'.Most devices in a Unix-like operating system are accessed
through device-nodes, sometimes also called special files.
These files are usually located under the directory
/dev in the file system hierarchy. Until
devfs is fully integrated into FreeBSD, each device node must be
created statically and independent of the existence of the
associated device driver. Most device nodes on the system are
created by running MAKEDEV.Device drivers can roughly be broken down into two
categories; character and network device drivers.Dynamic Kernel Linker Facility - KLDThe kld interface allows system administrators to
dynamically add and remove functionality from a running system.
This allows device driver writers to load their new changes into
a running kernel without constantly rebooting to test
changes.The kld interface is used through the following
administrator commands :
kldload - loads a new kernel
modulekldunload - unloads a kernel
modulekldstat - lists the currently loadded
modulesSkeleton Layout of a kernel module/*
* KLD Skeleton
* Inspired by Andrew Reiter's Daemonnews article
*/
#include <sys/types.h>
#include <sys/module.h>
#include <sys/systm.h> /* uprintf */
#include <sys/errno.h>
#include <sys/param.h> /* defines used in kernel.h */
#include <sys/kernel.h> /* types used in module initialization */
/*
* Load handler that deals with the loading and unloading of a KLD.
*/
static int
skel_loader(struct module *m, int what, void *arg)
{
int err = 0;
switch (what) {
case MOD_LOAD: /* kldload */
uprintf("Skeleton KLD loaded.\n");
break;
case MOD_UNLOAD:
uprintf("Skeleton KLD unloaded.\n");
break;
default:
err = EINVAL;
break;
}
return(err);
}
/* Declare this module to the rest of the kernel */
static moduledata_t skel_mod = {
"skel",
skel_loader,
NULL
};
DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY);MakefileFreeBSD provides a makefile include that you can use to
quickly compile your kernel addition.SRCS=skeleton.c
KMOD=skeleton
.include <bsd.kmod.mk>Simply running make with this makefile
will create a file skeleton.ko that can
be loaded into your system by typing :
&prompt.root
kldload -v ./skeleton.koAccessing a device driverUnix provides a common set of system calls for user
applications to use. The upper layers of the kernel dispatch
these calls to the corresponding device driver when a user
accesses a device node. The /dev/MAKEDEV
script makes most of the device nodes for your system but if you
are doing your own driver development it may be necessary to
create your own device nodes with mknodCreating static device nodesThe mknod command requires four
arguments to create a device node. You must specify the name
of this device node, the type of device, the major number of
the device, and the minor number of the device.Dynamic device nodesThe device filesystem, or devfs, provides access to the
kernel's device namespace in the global filesystem namespace.
This eliminates the problems of potentially having a device
driver without a static device node, or a device node without
an installed device driver. Devfs is still a work in
progress, but it is already working quite nice.Character DevicesA character device driver is one that transfers data
directly to and from a user process. This is the most common
type of device driver and there are plenty of simple examples in
the source tree.This simple example pseudo-device remembers whatever values
you write to it and can then supply them back to you when you
read from it./*
* Simple `echo' pseudo-device KLD
*
* Murray Stokely
*/
#define MIN(a,b) (((a) < (b)) ? (a) : (b))
#include <sys/types.h>
#include <sys/module.h>
#include <sys/systm.h> /* uprintf */
#include <sys/errno.h>
#include <sys/param.h> /* defines used in kernel.h */
#include <sys/kernel.h> /* types used in module initialization */
#include <sys/conf.h> /* cdevsw struct */
#include <sys/uio.h> /* uio struct */
#include <sys/malloc.h>
#define BUFFERSIZE 256
/* Function prototypes */
d_open_t echo_open;
d_close_t echo_close;
d_read_t echo_read;
d_write_t echo_write;
/* Character device entry points */
static struct cdevsw echo_cdevsw = {
echo_open,
echo_close,
echo_read,
echo_write,
noioctl,
nopoll,
nommap,
nostrategy,
"echo",
33, /* reserved for lkms - /usr/src/sys/conf/majors */
nodump,
nopsize,
D_TTY,
-1
};
typedef struct s_echo {
char msg[BUFFERSIZE];
int len;
} t_echo;
/* vars */
static dev_t sdev;
static int len;
static int count;
static t_echo *echomsg;
MALLOC_DECLARE(M_ECHOBUF);
MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module");
/*
* This function acts is called by the kld[un]load(2) system calls to
* determine what actions to take when a module is loaded or unloaded.
*/
static int
echo_loader(struct module *m, int what, void *arg)
{
int err = 0;
switch (what) {
case MOD_LOAD: /* kldload */
sdev = make_dev(&echo_cdevsw,
0,
UID_ROOT,
GID_WHEEL,
0600,
"echo");
/* kmalloc memory for use by this driver */
/* malloc(256,M_ECHOBUF,M_WAITOK); */
MALLOC(echomsg, t_echo *, sizeof(t_echo), M_ECHOBUF, M_WAITOK);
printf("Echo device loaded.\n");
break;
case MOD_UNLOAD:
destroy_dev(sdev);
FREE(echomsg,M_ECHOBUF);
printf("Echo device unloaded.\n");
break;
default:
err = EINVAL;
break;
}
return(err);
}
int
echo_open(dev_t dev, int oflags, int devtype, struct proc *p)
{
int err = 0;
uprintf("Opened device \"echo\" successfully.\n");
return(err);
}
int
echo_close(dev_t dev, int fflag, int devtype, struct proc *p)
{
uprintf("Closing device \"echo.\"\n");
return(0);
}
/*
* The read function just takes the buf that was saved via
* echo_write() and returns it to userland for accessing.
* uio(9)
*/
int
echo_read(dev_t dev, struct uio *uio, int ioflag)
{
int err = 0;
int amt;
/* How big is this read operation? Either as big as the user wants,
or as big as the remaining data */
amt = MIN(uio->uio_resid, (echomsg->len - uio->uio_offset > 0) ? echomsg->len - uio->uio_offset : 0);
if ((err = uiomove(echomsg->msg + uio->uio_offset,amt,uio)) != 0) {
uprintf("uiomove failed!\n");
}
return err;
}
/*
* echo_write takes in a character string and saves it
* to buf for later accessing.
*/
int
echo_write(dev_t dev, struct uio *uio, int ioflag)
{
int err = 0;
/* Copy the string in from user memory to kernel memory */
err = copyin(uio->uio_iov->iov_base, echomsg->msg, MIN(uio->uio_iov->iov_len,BUFFERSIZE));
/* Now we need to null terminate */
*(echomsg->msg + MIN(uio->uio_iov->iov_len,BUFFERSIZE)) = 0;
/* Record the length */
echomsg->len = MIN(uio->uio_iov->iov_len,BUFFERSIZE);
if (err != 0) {
uprintf("Write failed: bad address!\n");
}
count++;
return(err);
}
DEV_MODULE(echo,echo_loader,NULL);To install this driver you will first need to make a node on
your filesystem with a command such as : &prompt.root mknod /dev/echo c 33 0With this driver loaded you should now be able to type
something like :&prompt.root echo -n "Test Data" > /dev/echo
&prompt.root cat /dev/echo
Test DataReal hardware devices in the next chapter..Additional Resources
Dynamic
Kernel Linker (KLD) Facility Programming Tutorial -
- Daemonnews October 2000
+ Daemonnews October 2000
How
to Write Kernel Drivers with NEWBUS - Daemonnews July
+ url="http://www.daemonnews.org/">Daemonnews July
2000Network DriversDrivers for network devices do not use device nodes in order
to be accessed. Their selection is based on other decisions
made inside the kernel and instead of calling open(), use of a
network device is generally introduced by using the system call
socket(2).man ifnet(), loopback device, Bill Paul's drivers,
etc..
diff --git a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
index 0210d7ab45..5473da05a6 100644
--- a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
@@ -1,1587 +1,1587 @@
IPv6 InternalsIPv6/IPsec ImplementationContributed by &a.shin;, 5 March
2000.This section should explain IPv6 and IPsec related implementation
internals. These functionalities are derived from KAME project
+ url="http://www.kame.net/">KAME project
IPv6ConformanceThe IPv6 related functions conforms, or tries to conform to
the latest set of IPv6 specifications. For future reference we list
some of the relevant documents below (NOTE: this
is not a complete list - this is too hard to maintain...).For details please refer to specific chapter in the document,
RFCs, manpages, or comments in the source code.Conformance tests have been performed on the KAME STABLE kit
at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/
. We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/) in the
past, with our past snapshots.RFC1639: FTP Operation Over Big Address Records
(FOOBAR)RFC2428 is preferred over RFC1639. FTP clients will
first try RFC2428, then RFC1639 if failed.RFC1886: DNS Extensions to support IPv6RFC1933: Transition Mechanisms for IPv6 Hosts and
RoutersIPv4 compatible address is not supported.automatic tunneling (described in 4.3 of this RFC) is not
supported.&man.gif.4; interface implements IPv[46]-over-IPv[46]
tunnel in a generic way, and it covers "configured tunnel"
described in the spec. See 23.5.1.5
in this document for details.RFC1981: Path MTU Discovery for IPv6RFC2080: RIPng for IPv6usr.sbin/route6d support this.RFC2292: Advanced Sockets API for IPv6For supported library functions/kernel APIs, see
sys/netinet6/ADVAPI.RFC2362: Protocol Independent Multicast-Sparse
Mode (PIM-SM)RFC2362 defines packet formats for PIM-SM.
draft-ietf-pim-ipv6-01.txt is
written based on this.RFC2373: IPv6 Addressing Architecturesupports node required addresses, and conforms to
the scope requirement.RFC2374: An IPv6 Aggregatable Global Unicast Address
Formatsupports 64-bit length of Interface ID.RFC2375: IPv6 Multicast Address AssignmentsUserland applications use the well-known addresses
assigned in the RFC.RFC2428: FTP Extensions for IPv6 and NATsRFC2428 is preferred over RFC1639. FTP clients will
first try RFC2428, then RFC1639 if failed.RFC2460: IPv6 specificationRFC2461: Neighbor discovery for IPv6See 23.5.1.2
in this document for details.RFC2462: IPv6 Stateless Address AutoconfigurationSee 23.5.1.4 in this
document for details.RFC2463: ICMPv6 for IPv6 specificationSee 23.5.1.9 in this
document for details.RFC2464: Transmission of IPv6 Packets over Ethernet
NetworksRFC2465: MIB for IPv6: Textual Conventions and General
GroupNecessary statistics are gathered by the kernel. Actual
IPv6 MIB support is provided as a patchkit for ucd-snmp.RFC2466: MIB for IPv6: ICMPv6 groupNecessary statistics are gathered by the kernel. Actual
IPv6 MIB support is provided as patchkit for ucd-snmp.RFC2467: Transmission of IPv6 Packets over FDDI
NetworksRFC2497: Transmission of IPv6 packet over ARCnet
NetworksRFC2553: Basic Socket Interface Extensions for IPv6IPv4 mapped address (3.7) and special behavior of IPv6
wildcard bind socket (3.8) are supported. See 23.5.1.12
in this document for details.RFC2675: IPv6 JumbogramsSee 23.5.1.7 in
this document for details.RFC2710: Multicast Listener Discovery for IPv6RFC2711: IPv6 router alert optiondraft-ietf-ipngwg-router-renum-08: Router
renumbering for IPv6draft-ietf-ipngwg-icmp-namelookups-02:
IPv6 Name Lookups Through ICMPdraft-ietf-ipngwg-icmp-name-lookups-03:
IPv6 Name Lookups Through ICMPdraft-ietf-pim-ipv6-01.txt:
PIM for IPv6&man.pim6dd.8; implements dense mode. &man.pim6sd.8;
implements sparse mode.draft-itojun-ipv6-tcp-to-anycast-00:
Disconnecting TCP connection toward IPv6 anycast addressdraft-yamamoto-wideipv6-comm-model-00See 23.5.1.6 in this
document for details.draft-ietf-ipngwg-scopedaddr-format-00.txt
: An Extension of Format for IPv6 Scoped
AddressesNeighbor DiscoveryNeighbor Discovery is fairly stable. Currently Address
Resolution, Duplicated Address Detection, and Neighbor Unreachability
Detection are supported. In the near future we will be adding Proxy
Neighbor Advertisement support in the kernel and Unsolicited Neighbor
Advertisement transmission command as admin tool.If DAD fails, the address will be marked "duplicated" and
message will be generated to syslog (and usually to console). The
"duplicated" mark can be checked with &man.ifconfig.8;. It is
administrators' responsibility to check for and recover from DAD
failures. The behavior should be improved in the near future.Some of the network driver loops multicast packets back to itself,
even if instructed not to do so (especially in promiscuous mode).
In such cases DAD may fail, because DAD engine sees inbound NS packet
(actually from the node itself) and considers it as a sign of duplicate.
You may want to look at #if condition marked "heuristics" in
sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
fragment in "heuristics" section is not spec conformant).Neighbor Discovery specification (RFC2461) does not talk about
neighbor cache handling in the following cases:when there was no neighbor cache entry, node
received unsolicited RS/NS/NA/redirect packet without
link-layer addressneighbor cache handling on medium without link-layer
address (we need a neighbor cache entry for IsRouter bit)For first case, we implemented workaround based on discussions
on IETF ipngwg mailing list. For more details, see the comments in
the source code and email thread started from (IPng 7155), dated
Feb 6 1999.IPv6 on-link determination rule (RFC2461) is quite different
from assumptions in BSD network code. At this moment, no on-link
determination rule is supported where default router list is empty
(RFC2461, section 5.2, last sentence in 2nd paragraph - note that
the spec misuse the word "host" and "node" in several places in
the section).To avoid possible DoS attacks and infinite loops, only 10
options on ND packet is accepted now. Therefore, if you have 20
prefix options attached to RA, only the first 10 prefixes will be
recognized. If this troubles you, please ask it on FREEBSD-CURRENT
mailing list and/or modify nd6_maxndopt in
sys/netinet6/nd6.c. If there are high demands
we may provide sysctl knob for the variable.Scope IndexIPv6 uses scoped addresses. Therefore, it is very important to
specify scope index (interface index for link-local address, or
site index for site-local address) with an IPv6 address. Without
scope index, scoped IPv6 address is ambiguous to the kernel, and
kernel will not be able to determine the outbound interface for a
packet.Ordinary userland applications should use advanced API
(RFC2292) to specify scope index, or interface index. For similar
purpose, sin6_scope_id member in sockaddr_in6 structure is defined
in RFC2553. However, the semantics for sin6_scope_id is rather vague.
If you care about portability of your application, we suggest you to
use advanced API rather than sin6_scope_id.In the kernel, an interface index for link-local scoped address is
embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address. For
example, you may see something like:
fe80:1::200:f8ff:fe01:6317
in the routing table and interface address structure (struct
in6_ifaddr). The address above is a link-local unicast address
which belongs to a network interface whose interface identifier is 1.
The embedded index enables us to identify IPv6 link local
addresses over multiple interfaces effectively and with only a
little code change.Routing daemons and configuration programs, like &man.route6d.8;
and &man.ifconfig.8;, will need to manipulate the "embedded" scope
index. These programs use routing sockets and ioctls (like
SIOCGIFADDR_IN6) and the kernel API will return IPv6 addresses with
2nd 16bit-word filled in. The APIs are for manipulating kernel
internal structure. Programs that use these APIs have to be prepared
about differences in kernels anyway.When you specify scoped address to the command line, NEVER write
the embedded form (such as ff02:1::1 or fe80:2::fedc). This is not
supposed to work. Always use standard form, like ff02::1 or
fe80::fedc, with command line option for specifying interface (like
ping6 -I ne0 ff02::1). In general, if a command
does not have command line option to specify outgoing interface, that
command is not ready to accept scoped address. This may seem to be
opposite from IPv6's premise to support "dentist office" situation.
We believe that specifications need some improvements for this.Some of the userland tools support extended numeric IPv6 syntax,
as documented in
draft-ietf-ipngwg-scopedaddr-format-00.txt. You
can specify outgoing link, by using name of the outgoing interface
like "fe80::1%ne0". This way you will be able to specify link-local
scoped address without much trouble.To use this extension in your program, you'll need to use
&man.getaddrinfo.3;, and &man.getnameinfo.3; with NI_WITHSCOPEID.
The implementation currently assumes 1-to-1 relationship between a
link and an interface, which is stronger than what specs say.Plug and PlayMost of the IPv6 stateless address autoconfiguration is implemented
in the kernel. Neighbor Discovery functions are implemented in the
kernel as a whole. Router Advertisement (RA) input for hosts is
implemented in the kernel. Router Solicitation (RS) output for
endhosts, RS input for routers, and RA output for routers are
implemented in the userland.Assignment of link-local, and special addressesIPv6 link-local address is generated from IEEE802 address
(Ethernet MAC address). Each of interface is assigned an IPv6
link-local address automatically, when the interface becomes up
(IFF_UP). Also, direct route for the link-local address is added
to routing table.Here is an output of netstat command:Internet6:
Destination Gateway Flags Netif Expire
fe80:1::%ed0/64 link#1 UC ed0
fe80:2::%ep0/64 link#2 UC ep0Interfaces that has no IEEE802 address (pseudo interfaces
like tunnel interfaces, or ppp interfaces) will borrow IEEE802
address from other interfaces, such as Ethernet interfaces,
whenever possible. If there is no IEEE802 hardware attached,
last-resort pseudorandom value, which is from MD5(hostname), will
be used as source of link-local address. If it is not suitable
for your usage, you will need to configure the link-local address
manually.If an interface is not capable of handling IPv6 (such as
lack of multicast support), link-local address will not be
assigned to that interface. See section 2 for details.Each interface joins the solicited multicast address and the
link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317
and ff02::1, respectively, on the link the interface is attached).
In addition to a link-local address, the loopback address (::1)
will be assigned to the loopback interface. Also, ::1/128 and
ff01::/32 are automatically added to routing table, and loopback
interface joins node-local multicast group ff01::1.Stateless address autoconfiguration on hostsIn IPv6 specification, nodes are separated into two categories:
routers and hosts. Routers
forward packets addressed to others, hosts does not forward the
packets. net.inet6.ip6.forwarding defines whether this node is
router or host (router if it is 1, host if it is 0).When a host hears Router Advertisement from the router, a host
may autoconfigure itself by stateless address autoconfiguration.
This behavior can be controlled by net.inet6.ip6.accept_rtadv (host
autoconfigures itself if it is set to 1). By autoconfiguration,
network address prefix for the receiving interface (usually global
address prefix) is added. Default route is also configured.
Routers periodically generate Router Advertisement packets. To
request an adjacent router to generate RA packet, a host can
transmit Router Solicitation. To generate a RS packet at any time,
use the rtsol command. &man.rtsold.8; daemon is
also available. &man.rtsold.8; generates Router Solicitation whenever
necessary, and it works great for nomadic usage (notebooks/laptops).
If one wishes to ignore Router Advertisements, use sysctl to set
net.inet6.ip6.accept_rtadv to 0.To generate Router Advertisement from a router, use the
&man.rtadvd.8 daemon.Note that, IPv6 specification assumes the following items, and
nonconforming cases are left unspecified:Only hosts will listen to router advertisementsHosts have single network interface (except loopback)Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv
on routers, or multi-interface host. A misconfigured node can
behave strange (nonconforming configuration allowed for those who
would like to do some experiments).To summarize the sysctl knob: accept_rtadv forwarding role of the node
--- --- ---
0 0 host (to be manually configured)
0 1 router
1 0 autoconfigured host
(spec assumes that host has single
interface only, autoconfigured host
with multiple interface is
out-of-scope)
1 1 invalid, or experimental
(out-of-scope of spec)RFC2462 has validation rule against incoming RA prefix
information option, in 5.5.3 (e). This is to protect hosts from
malicious (or misconfigured) routers that advertise very short
prefix lifetime. There was an update from Jim Bound to ipngwg
mailing list (look for "(ipng 6712)" in the archive) and it is
implemented Jim's update.See 23.5.1.2 in
the document for relationship between DAD and
autoconfiguration.Generic tunnel interfaceGIF (Generic InterFace) is a pseudo interface for configured
tunnel. Details are described in &man.gif.4;. Currentlyv6 in v6v6 in v4v4 in v6v4 in v4are available. Use &man.gifconfig.8; to assign physical (outer)
source and destination address to gif interfaces. Configuration that
uses same address family for inner and outer IP header (v4 in v4, or
v6 in v6) is dangerous. It is very easy to configure interfaces and
routing tables to perform infinite level of tunneling.
Please be warned.gif can be configured to be ECN-friendly. See 23.5.4.5 for ECN-friendliness of
tunnels, and &man.gif.4; for how to configure.If you would like to configure an IPv4-in-IPv6 tunnel with gif
interface, read &man.gif.4; carefully. You will need to
remove IPv6 link-local address automatically assigned to the gif
interface.Source Address SelectionCurrent source selection rule is scope oriented (there are some
exceptions - see below). For a given destination, a source IPv6
address is selected by the following rule:If the source address is explicitly specified by
the user (e.g. via the advanced API), the specified address
is used.If there is an address assigned to the outgoing
interface (which is usually determined by looking up the
routing table) that has the same scope as the destination
address, the address is used.This is the most typical case.If there is no address that satisfies the above
condition, choose a global address assigned to one of
the interfaces on the sending node.If there is no address that satisfies the above condition,
and destination address is site local scope, choose a site local
address assigned to one of the interfaces on the sending node.
If there is no address that satisfies the above condition,
choose the address associated with the routing table entry for the
destination. This is the last resort, which may cause scope
violation.For instance, ::1 is selected for ff01::1,
fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note
that embedded interface index - described in 23.5.1.3 - helps us
choose the right source address. Those embedded indices will not
be on the wire). If the outgoing interface has multiple address for
the scope, a source is selected longest match basis (rule 3). Suppose
3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
are given to the outgoing interface. 3ffe:501:808:1:200:f8ff:fe01:6317
is chosen as the source for the destination 3ffe:501:800::1.Note that the above rule is not documented in the IPv6 spec.
It is considered "up to implementation" item. There are some cases
where we do not use the above rule. One example is connected TCP
session, and we use the address kept in tcb as the source. Another
example is source address for Neighbor Advertisement. Under the spec
(RFC2461 7.2.2) NA's source should be the target address of the
corresponding NS's target. In this case we follow the spec rather
than the above longest-match rule.For new connections (when rule 1 does not apply), deprecated
addresses (addresses with preferred lifetime = 0) will not be chosen
as source address if other choices are available. If no other choices
are available, deprecated address will be used as a last resort. If
there are multiple choice of deprecated addresses, the above scope
rule will be used to choose from those deprecated addresses. If you
would like to prohibit the use of deprecated address for some reason,
configure net.inet6.ip6.use_deprecated to 0. The issue related to
deprecated address is described in RFC2462 5.5.4 (NOTE: there is
some debate underway in IETF ipngwg on how to use "deprecated"
address).Jumbo PayloadThe Jumbo Payload hop-by-hop option is implemented and can
be used to send IPv6 packets with payloads longer than 65,535 octets.
But currently no physical interface whose MTU is more than 65,535 is
supported, so such payloads can be seen only on the loopback
interface (i.e. lo0).If you want to try jumbo payloads, you first have to reconfigure
the kernel so that the MTU of the loopback interface is more than
65,535 bytes; add the following to the kernel configuration file:
options "LARGE_LOMTU" #To test jumbo payload
and recompile the new kernel.Then you can test jumbo payloads by the &man.ping6.8; command
with -b and -s options. The -b option must be specified to enlarge
the size of the socket buffer and the -s option specifies the length
of the packet, which should be more than 65,535. For example,
type as follows:
&prompt.user; ping6 -b 70000 -s 68000 ::1The IPv6 specification requires that the Jumbo Payload option
must not be used in a packet that carries a fragment header. If
this condition is broken, an ICMPv6 Parameter Problem message must
be sent to the sender. specification is followed, but you cannot
usually see an ICMPv6 error caused by this requirement.When an IPv6 packet is received, the frame length is checked and
compared to the length specified in the payload length field of the
IPv6 header or in the value of the Jumbo Payload option, if any. If
the former is shorter than the latter, the packet is discarded and
statistics are incremented. You can see the statistics as output of
&man.netstat.8; command with `-s -p ip6' option: &prompt.user; netstat -s -p ip6
ip6:
(snip)
1 with data size < data lengthSo, kernel does not send an ICMPv6 error unless the erroneous
packet is an actual Jumbo Payload, that is, its packet size is more
than 65,535 bytes. As described above, currently no physical interface
with such a huge MTU is supported, so it rarely returns an
ICMPv6 error.TCP/UDP over jumbogram is not supported at this moment. This
is because we have no medium (other than loopback) to test this.
Contact us if you need this.IPsec does not work on jumbograms. This is due to some
specification twists in supporting AH with jumbograms (AH header
size influences payload length, and this makes it real hard to
authenticate inbound packet with jumbo payload option as well as AH).
There are fundamental issues in *BSD support for jumbograms.
We would like to address those, but we need more time to finalize
these. To name a few:mbuf pkthdr.len field is typed as "int" in 4.4BSD, so
it will not hold jumbogram with len > 2G on 32bit architecture
CPUs. If we would like to support jumbogram properly, the field
must be expanded to hold 4G + IPv6 header + link-layer header.
Therefore, it must be expanded to at least int64_t
(u_int32_t is NOT enough).We mistakingly use "int" to hold packet length in many
places. We need to convert them into larger integral type.
It needs a great care, as we may experience overflow during
packet length computation.We mistakingly check for ip6_plen field of IPv6 header
for packet payload length in various places. We should be
checking mbuf pkthdr.len instead. ip6_input() will perform
sanity check on jumbo payload option on input, and we can
safely use mbuf pkthdr.len afterwards.TCP code needs a careful update in bunch of places, of
course.Loop prevention in header processingIPv6 specification allows arbitrary number of extension headers
to be placed onto packets. If we implement IPv6 packet processing
code in the way BSD IPv4 code is implemented, kernel stack may
overflow due to long function call chain. sys/netinet6 code
is carefully designed to avoid kernel stack overflow. Because of
this, sys/netinet6 code defines its own protocol switch
structure, as "struct ip6protosw" (see
netinet6/ip6protosw.h). There is no such
update to IPv4 part (sys/netinet) for compatibility, but small
change is added to its pr_input() prototype. So "struct ipprotosw"
is also defined. Because of this, if you receive IPsec-over-IPv4
packet with massive number of IPsec headers, kernel stack may blow
up. IPsec-over-IPv6 is okay. (Off-course, for those all IPsec
headers to be processed, each such IPsec header must pass each
IPsec check. So an anonymous attacker won't be able to do such an
attack.)ICMPv6After RFC2463 was published, IETF ipngwg has decided to
disallow ICMPv6 error packet against ICMPv6 redirect, to prevent
ICMPv6 storm on a network medium. This is already implemented
into the kernel.ApplicationsFor userland programming, we support IPv6 socket API as
specified in RFC2553, RFC2292 and upcoming Internet drafts.TCP/UDP over IPv6 is available and quite stable. You can
enjoy &man.telnet.1;, &man.ftp.1;, &man.rlogin.1;, &man.rsh.1;,
&man.ssh.1, etc. These applications are protocol independent.
That is, they automatically chooses IPv4 or IPv6 according to DNS.
Kernel InternalsWhile ip_forward() calls ip_output(), ip6_forward() directly
calls if_output() since routers must not divide IPv6 packets into
fragments.ICMPv6 should contain the original packet as long as possible
up to 1280. UDP6/IP6 port unreach, for instance, should contain
all extension headers and the *unchanged* UDP6 and IP6 headers.
So, all IP6 functions except TCP never convert network byte
order into host byte order, to save the original packet.tcp_input(), udp6_input() and icmp6_input() can't assume that
IP6 header is preceding the transport headers due to extension
headers. So, in6_cksum() was implemented to handle packets whose IP6
header and transport header is not continuous. TCP/IP6 nor UDP6/IP6
header structure don't exist for checksum calculation.To process IP6 header, extension headers and transport headers
easily, network drivers are now required to store packets in one
internal mbuf or one or more external mbufs. A typical old driver
prepares two internal mbufs for 96 - 204 bytes data, however, now
such packet data is stored in one external mbuf.netstat -s -p ip6 tells you whether or not
your driver conforms such requirement. In the following example,
"cce0" violates the requirement. (For more information, refer to
Section 2.)Mbuf statistics:
317 one mbuf
two or more mbuf::
lo0 = 8
cce0 = 10
3282 one ext mbuf
0 two or more ext mbuf
Each input function calls IP6_EXTHDR_CHECK in the beginning to
check if the region between IP6 and its header is continuous.
IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has M_LOOP flag,
that is, the packet comes from the loopback interface. m_pullup()
is never called for packets coming from physical network interfaces.
Both IP and IP6 reassemble functions never call m_pullup().IPv4 mapped address and IPv6 wildcard socketRFC2553 describes IPv4 mapped address (3.7) and special behavior
of IPv6 wildcard bind socket (3.8). The spec allows you to:Accept IPv4 connections by AF_INET6 wildcard bind
socket.Transmit IPv4 packet over AF_INET6 socket by using
special form of the address like ::ffff:10.1.1.1.but the spec itself is very complicated and does not specify
how the socket layer should behave. Here we call the former one
"listening side" and the latter one "initiating side", for
reference purposes.You can perform wildcard bind on both of the address families,
on the same port.The following table show the behavior of FreeBSD 4.x.listening side initiating side
(AF_INET6 wildcard (connection to ::ffff:10.1.1.1)
socket gets IPv4 conn.)
--- ---
FreeBSD 4.x configurable supported
default: enabled
The following sections will give you more details, and how you can
configure the behavior.Comments on listening side:It looks that RFC2553 talks too little on wildcard bind issue,
especially on the port space issue, failure mode and relationship
between AF_INET/INET6 wildcard bind. There can be several separate
interpretation for this RFC which conform to it but behaves differently.
So, to implement portable application you should assume nothing
about the behavior in the kernel. Using &man.getaddrinfo.3; is the
safest way. Port number space and wildcard bind issues were discussed
in detail on ipv6imp mailing list, in mid March 1999 and it looks
that there's no concrete consensus (means, up to implementers).
You may want to check the mailing list archives.If a server application would like to accept IPv4 and IPv6
connections, there will be two alternatives.One is using AF_INET and AF_INET6 socket (you'll need two
sockets). Use &man.getaddrinfo.3; with AI_PASSIVE into ai_flags,
and &man.socket.2; and &man.bind.2; to all the addresses returned.
By opening multiple sockets, you can accept connections onto the
socket with proper address family. IPv4 connections will be
accepted by AF_INET socket, and IPv6 connections will be accepted
by AF_INET6 socket.Another way is using one AF_INET6 wildcard bind socket. Use
&man.getaddrinfo.3; with AI_PASSIVE into ai_flags and with
AF_INET6 into ai_family, and set the 1st argument hostname to
NULL. And &man.socket.2; and &man.bind.2; to the address returned.
(should be IPv6 unspecified addr). You can accept either of IPv4
and IPv6 packet via this one socket.To support only IPv6 traffic on AF_INET6 wildcard binded socket
portably, always check the peer address when a connection is made
toward AF_INET6 listening socket. If the address is IPv4 mapped
address, you may want to reject the connection. You can check the
condition by using IN6_IS_ADDR_V4MAPPED() macro.To resolve this issue more easily, there is system dependent
&man.setsockopt.2; option, IPV6_BINDV6ONLY, used like below. int on;
setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
(char *)&on, sizeof (on)) < 0));
When this call succeed, then this socket only receive IPv6
packets.Comments on initiating side:Advise to application implementers: to implement a portable
IPv6 application (which works on multiple IPv6 kernels), we believe
that the following is the key to the success:NEVER hardcode AF_INET nor AF_INET6.Use &man.getaddrinfo.3; and &man.getnameinfo.3;
throughout the system. Never use gethostby*(), getaddrby*(),
inet_*() or getipnodeby*(). (To update existing applications
to be IPv6 aware easily, sometime getipnodeby*() will be
useful. But if possible, try to rewrite the code to use
&man.getaddrinfo.3; and &man.getnameinfo.3;.)If you would like to connect to destination, use
&man.getaddrinfo.3; and try all the destination returned,
like &man.telnet.1; does.Some of the IPv6 stack is shipped with buggy
&man.getaddrinfo.3;. Ship a minimal working version with
your application and use that as last resort.If you would like to use AF_INET6 socket for both IPv4 and
IPv6 outgoing connection, you will need to use &man.getipnodebyname.3;.
When you would like to update your existing application to be IPv6
aware with minimal effort, this approach might be chosen. But please
note that it is a temporal solution, because &man.getipnodebyname.3;
itself is not recommended as it does not handle scoped IPv6 addresses
at all. For IPv6 name resolution, &man.getaddrinfo.3; is the
preferred API. So you should rewrite your application to use
&man.getaddrinfo.3;, when you get the time to do it.When writing applications that make outgoing connections,
story goes much simpler if you treat AF_INET and AF_INET6 as totally
separate address family. {set,get}sockopt issue goes simpler,
DNS issue will be made simpler. We do not recommend you to rely
upon IPv4 mapped address.unified tcp and inpcb codeFreeBSD 4.x uses shared tcp code between IPv4 and IPv6
(from sys/netinet/tcp*) and separate udp4/6 code. It uses
unified inpcb structure.The platform can be configured to support IPv4 mapped address.
Kernel configuration is summarized as follows:By default, AF_INET6 socket will grab IPv4
connections in certain condition, and can initiate
connection to IPv4 destination embedded in IPv4 mapped
IPv6 address.You can disable it on entire system with sysctl like
below.sysctl -w net.inet6.ip6.mapped_addr=0listening sideEach socket can be configured to support special AF_INET6
wildcard bind (enabled by default). You can disable it on
each socket basis with &man.setsockopt.2; like below. int on;
setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
(char *)&on, sizeof (on)) < 0));
Wildcard AF_INET6 socket grabs IPv4 connection if and only
if the following conditions are satisfied:there's no AF_INET socket that matches the IPv4
connectionthe AF_INET6 socket is configured to accept IPv4
traffic, i.e. getsockopt(IPV6_BINDV6ONLY) returns 0.There's no problem with open/close ordering.initiating sideFreeBSD 4.x supports outgoing connection to IPv4 mapped
address (::ffff:10.1.1.1), if the node is configured to support
IPv4 mapped address.sockaddr_storageWhen RFC2553 was about to be finalized, there was discussion on
how struct sockaddr_storage members are named. One proposal is to
prepend "__" to the members (like "__ss_len") as they should not be
touched. The other proposal was that don't prepend it (like "ss_len")
as we need to touch those members directly. There was no clear
consensus on it.As a result, RFC2553 defines struct sockaddr_storage as
follows: struct sockaddr_storage {
u_char __ss_len; /* address length */
u_char __ss_family; /* address family */
/* and bunch of padding */
};
On the contrary, XNET draft defines as follows: struct sockaddr_storage {
u_char ss_len; /* address length */
u_char ss_family; /* address family */
/* and bunch of padding */
};
In December 1999, it was agreed that RFC2553bis should pick
the latter (XNET) definition.Current implementation conforms to XNET definition, based on
RFC2553bis discussion.If you look at multiple IPv6 implementations, you will be able
to see both definitions. As an userland programmer, the most
portable way of dealing with it is to:ensure ss_family and/or ss_len are available on the
platform, by using GNU autoconf,have -Dss_family=__ss_family to unify all occurrences
(including header file) into __ss_family, ornever touch __ss_family. cast to sockaddr * and use sa_family
like: struct sockaddr_storage ss;
family = ((struct sockaddr *)&ss)->sa_family
Network DriversNow following two items are required to be supported by standard
drivers:mbuf clustering requirement. In this stable release, we
changed MINCLSIZE into MHLEN+1 for all the operating systems
in order to make all the drivers behave as we expect.multicast. If &man.ifmcstat.8; yields no multicast group for
a interface, that interface has to be patched.If any of the driver don't support the requirements, then
the driver can't be used for IPv6 and/or IPsec communication. If
you find any problem with your card using IPv6/IPsec, then, please
report it to freebsd-bugs@FreeBSD.org.(NOTE: In the past we required all PCMCIA drivers to have a
call to in6_ifattach(). We have no such requirement any more)TranslatorWe categorize IPv4/IPv6 translator into 4 types:Translator A --- It is used in the early
stage of transition to make it possible to establish a
connection from an IPv6 host in an IPv6 island to an IPv4 host
in the IPv4 ocean.Translator B --- It is used in the early
stage of transition to make it possible to establish a connection
from an IPv4 host in the IPv4 ocean to an IPv6 host in an
IPv6 island.Translator C --- It is used in the late
stage of transition to make it possible to establish a
connection from an IPv4 host in an IPv4 island to an IPv6 host
in the IPv6 ocean.Translator D --- It is used in the late
stage of transition to make it possible to establish a
connection from an IPv6 host in the IPv6 ocean to an IPv4 host
in an IPv4 island.TCP relay translator for category A is supported. This is called
"FAITH". We also provide IP header translator for category A.
(The latter is not yet put into FreeBSD 4.x yet.)FAITH TCP relay translatorFAITH system uses TCP relay daemon called &man.faithd.8; helped
by the kernel. FAITH will reserve an IPv6 address prefix, and relay
TCP connection toward that prefix to IPv4 destination.For example, if the reserved IPv6 prefix is
3ffe:0501:0200:ffff::, and the IPv6 destination for TCP connection
is 3ffe:0501:0200:ffff::163.221.202.12, the connection will be
relayed toward IPv4 destination 163.221.202.12. destination IPv4 node (163.221.202.12)
^
| IPv4 tcp toward 163.221.202.12
FAITH-relay dual stack node
^
| IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
source IPv6 node
&man.faithd.8; must be invoked on FAITH-relay dual stack
node.For more details, consult
src/usr.sbin/faithd/READMEIPsecIPsec is mainly organized by three components.Policy ManagementKey ManagementAH and ESP handlingPolicy ManagementThe kernel implements experimental policy management code.
There are two way to manage security policy. One is to configure
per-socket policy using &man.setsockopt.2;. In this cases, policy
configuration is described in &man.ipsec.set.policy.3;. The other
is to configure kernel packet filter-based policy using PF_KEY
interface, via &man.setkey.8;.The policy entry is not re-ordered with its
indexes, so the order of entry when you add is very significant.Key ManagementThe key management code implemented in this kit (sys/netkey)
is a home-brew PFKEY v2 implementation. This conforms to RFC2367.
The home-brew IKE daemon, "racoon" is included in the
kit (kame/kame/racoon). Basically you'll need to run racoon as
daemon, then setup a policy to require keys (like
ping -P 'out ipsec esp/transport//use').
The kernel will contact racoon daemon as necessary to exchange
keys.AH and ESP handlingIPsec module is implemented as "hooks" to the standard IPv4/IPv6
processing. When sending a packet, ip{,6}_output() checks if ESP/AH
processing is required by checking if a matching SPD (Security
Policy Database) is found. If ESP/AH is needed,
{esp,ah}{4,6}_output() will be called and mbuf will be updated
accordingly. When a packet is received, {esp,ah}4_input() will be
called based on protocol number, i.e. (*inetsw[proto])().
{esp,ah}4_input() will decrypt/check authenticity of the packet,
and strips off daisy-chained header and padding for ESP/AH. It is
safe to strip off the ESP/AH header on packet reception, since we
will never use the received packet in "as is" form.By using ESP/AH, TCP4/6 effective data segment size will be
affected by extra daisy-chained headers inserted by ESP/AH. Our
code takes care of the case.Basic crypto functions can be found in directory "sys/crypto".
ESP/AH transform are listed in {esp,ah}_core.c with wrapper functions.
If you wish to add some algorithm, add wrapper function in
{esp,ah}_core.c, and add your crypto algorithm code into
sys/crypto.Tunnel mode is partially supported in this release, with the
following restrictions:IPsec tunnel is not combined with GIF generic tunneling
interface. It needs a great care because we may create an
infinite loop between ip_output() and tunnelifp->if_output().
Opinion varies if it is better to unify them, or not.MTU and Don't Fragment bit (IPv4) considerations need more
checking, but basically works fine.Authentication model for AH tunnel must be revisited.
We'll need to improve the policy management engine,
eventually.Conformance to RFCs and IDsThe IPsec code in the kernel conforms (or, tries to conform)
to the following standards:"old IPsec" specification documented in
rfc182[5-9].txt"new IPsec" specification documented in
rfc240[1-6].txt,
rfc241[01].txt, rfc2451.txt
and draft-mcdonald-simple-ipsec-api-01.txt
(draft expired, but you can take from
ftp://ftp.kame.net/pub/internet-drafts/).
(NOTE: IKE specifications, rfc241[7-9].txt are
implemented in userland, as "racoon" IKE daemon)Currently supported algorithms are:old IPsec AHnull crypto checksum (no document, just for
debugging)keyed MD5 with 128bit crypto checksum
(rfc1828.txt)keyed SHA1 with 128bit crypto checksum
(no document)HMAC MD5 with 128bit crypto checksum
(rfc2085.txt)HMAC SHA1 with 128bit crypto checksum
(no document)old IPsec ESPnull encryption (no document, similar to
rfc2410.txt)DES-CBC mode (rfc1829.txt)new IPsec AHnull crypto checksum (no document,
just for debugging)keyed MD5 with 96bit crypto checksum
(no document)keyed SHA1 with 96bit crypto checksum
(no document)HMAC MD5 with 96bit crypto checksum
(rfc2403.txt)HMAC SHA1 with 96bit crypto checksum
(rfc2404.txt)new IPsec ESPnull encryption
(rfc2410.txt)DES-CBC with derived IV
(draft-ietf-ipsec-ciph-des-derived-01.txt,
draft expired)DES-CBC with explicit IV
(rfc2405.txt)3DES-CBC with explicit IV
(rfc2451.txt)BLOWFISH CBC
(rfc2451.txt)CAST128 CBC
(rfc2451.txt)RC5 CBC
(rfc2451.txt)each of the above can be combined with:ESP authentication with HMAC-MD5(96bit)ESP authentication with HMAC-SHA1(96bit)The following algorithms are NOT supported:old IPsec AHHMAC MD5 with 128bit crypto checksum + 64bit
replay prevention (rfc2085.txt)keyed SHA1 with 160bit crypto checksum + 32bit padding
(rfc1852.txt)IPsec (in kernel) and IKE (in userland as "racoon") has been
tested at several interoperability test events, and it is known to
interoperate with many other implementations well. Also, current
IPsec implementation as quite wide coverage for IPsec crypto
algorithms documented in RFC (we cover algorithms without intellectual
property issues only).ECN consideration on IPsec tunnelsECN-friendly IPsec tunnel is supported as described in
draft-ipsec-ecn-00.txt.Normal IPsec tunnel is described in RFC2401. On encapsulation,
IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
IP header to outer IP header. On decapsulation outer IP header
will be simply dropped. The decapsulation rule is not compatible
with ECN, since ECN bit on the outer IP TOS/traffic class field will be
lost.To make IPsec tunnel ECN-friendly, we should modify encapsulation
and decapsulation procedure. This is described in
http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt,
chapter 3.IPsec tunnel implementation can give you three behaviors, by
setting net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some
value:RFC2401: no consideration for ECN (sysctl value -1)ECN forbidden (sysctl value 0)ECN allowed (sysctl value 1)Note that the behavior is configurable in per-node manner,
not per-SA manner (draft-ipsec-ecn-00 wants per-SA configuration,
but it looks too much for me).The behavior is summarized as follows (see source code for
more detail):
encapsulate decapsulate
--- ---
RFC2401 copy all TOS bits drop TOS bits on outer
from inner to outer. (use inner TOS bits as is)
ECN forbidden copy TOS bits except for ECN drop TOS bits on outer
(masked with 0xfc) from inner (use inner TOS bits as is)
to outer. set ECN bits to 0.
ECN allowed copy TOS bits except for ECN use inner TOS bits with some
CE (masked with 0xfe) from change. if outer ECN CE bit
inner to outer. is 1, enable ECN CE bit on
set ECN CE bit to 0. the inner.
General strategy for configuration is as follows:if both IPsec tunnel endpoint are capable of ECN-friendly
behavior, you'd better configure both end to "ECN allowed"
(sysctl value 1).if the other end is very strict about TOS bit, use "RFC2401"
(sysctl value -1).in other cases, use "ECN forbidden" (sysctl value 0).The default behavior is "ECN forbidden" (sysctl value 0).For more information, please refer to:
http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt,
RFC2481 (Explicit Congestion Notification),
src/sys/netinet6/{ah,esp}_input.c(Thanks goes to Kenjiro Cho kjc@csl.sony.co.jp
for detailed analysis)InteroperabilityHere are (some of) platforms that KAME code have tested
IPsec/IKE interoperability in the past. Note that both ends may
have modified their implementation, so use the following list just
for reference purposes.Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure),
Ericsson ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel,
Microsoft WinNT, NIST (linux IPsec + plutoplus), Netscreen, OpenBSD,
RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba,
VPNet, Yamaha RT100i
diff --git a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
index 83899a6654..ca991b37bf 100644
--- a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
@@ -1,640 +1,640 @@
Kernel DebuggingContributed by &a.paul; and &a.joerg;Debugging a Kernel Crash Dump with gdbHere are some instructions for getting kernel debugging
working on a crash dump. They assume that you have enough swap
space for a crash dump. If you have multiple swap partitions
and the first one is too small to hold the dump, you can
configure your kernel to use an alternate dump device (in the
config kernel line), or you can specify an
alternate using the &man.dumpon.8; command. The best way to use
&man.dumpon.8; is to set the dumpdev variable
in /etc/rc.conf. Typically you want to
specify one of the swap devices specified in
/etc/fstab. Dumps to non-swap devices,
tapes for example, are currently not supported. Config your
kernel using config . See
- The FreeBSD
+ The FreeBSD
Handbook for details on configuring the FreeBSD
kernel.Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via /etc/rc.conf and /etc/rc.
Alternatively, you can hard-code the dump device via the
dump clause in the config line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.In the following, the term gdb refers to
the debugger gdb run in kernel debug
mode. This can be accomplished by starting the
gdb with the option . In
kernel debug mode, gdb changes its prompt to
(kgdb).If you are using FreeBSD 3 or earlier, you should make a stripped
copy of the debug kernel, rather than installing the large debug
kernel itself:&prompt.root; cp kernel kernel.debug
&prompt.root; strip -g kernelThis stage isn't necessary, but it is recommended. (In
FreeBSD 4 and later releases this step is performed automatically
at the end of the kernel make process.)
When the kernel has been stripped, either automatically or by
using the commands above, you may install it as usual by typing
make install.Note that older releases of FreeBSD (up to but not including
3.1) used a.out kernels by default, which must have their symbol
tables permanently resident in physical memory. With the larger
symbol table in an unstripped debug kernel, this is wasteful.
Recent FreeBSD releases use ELF kernels where this is no longer a
problem.If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the flag at the boot prompt, and
then perform the following steps:&prompt.root; fsck -p
&prompt.root; mount -a -t ufs # so your file system for /var/crash is writable
&prompt.root; savecore -N /kernel.panicked /var/crash
&prompt.root; exit # ...to multi-userThis instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.Now, after a crash dump, go to
/sys/compile/WHATEVER and run
gdb . From gdb do:
symbol-file kernel.debugexec-file /var/crash/kernel.0core-file /var/crash/vmcore.0
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.Here is a script log of a gdb session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver. 1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; cd /sys/compile/URIAH
3:&prompt.root; gdb -k kernel /var/crash/vmcore.1
4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
...done.
5:IdlePTD 1f3000
6:panic: because you said to!
7:current pcb at 1e3f70
8:Reading in symbols for ../../i386/i386/machdep.c...done.
9:(kgdb)where
10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
11:#1 0xf0115159 in panic ()
12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
13:#3 0xf010185e in db_fncall ()
14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
15:#5 0xf0101711 in db_command_loop ()
16:#6 0xf01040a0 in db_trap ()
17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
18:#8 0xf019d2eb in trap_fatal (...)
19:#9 0xf019ce60 in trap_pfault (...)
20:#10 0xf019cb2f in trap (...)
21:#11 0xf01932a1 in exception:calltrap ()
22:#12 0xf0191503 in cnopen (...)
23:#13 0xf0132c34 in spec_open ()
24:#14 0xf012d014 in vn_open ()
25:#15 0xf012a183 in open ()
26:#16 0xf019d4eb in syscall (...)
27:(kgdb)up 10
28:Reading in symbols for ../../i386/i386/trap.c...done.
29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
34:ss = -266427884}) (../../i386/i386/trap.c line 283)
35:283 (void) trap_pfault(&frame, FALSE);
36:(kgdb)frame frame->tf_ebp frame->tf_eip
37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
40:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
41:(kgdb)list
42:398
43:399 tp->t_state |= TS_CARR_ON;
44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */
45:401
46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200)
47:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
48:404 #else
49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag));
50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */
51:407 }
52:(kgdb)print tp
53:Reading in symbols for ../../i386/i386/cons.c...done.
54:$1 = (struct tty *) 0x1bae
55:(kgdb)print tp->t_line
56:$2 = 1767990816
57:(kgdb)up
58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
61:(kgdb)up
62:#2 0xf0132c34 in spec_open ()
63:(kgdb)up
64:#3 0xf012d014 in vn_open ()
65:(kgdb)up
66:#4 0xf012a183 in open ()
67:(kgdb)up
68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
73:673 error = (*callp->sy_call)(p, args, rval);
74:(kgdb)up
75:Initial frame selected; you cannot go up.
76:(kgdb)quit
77:&prompt.root; exit
78:exit
79:
80:Script done on Fri Dec 30 23:18:04 1994Comments to the above script:line 6:This is a dump taken from within DDB (see below), hence the
panic comment because you said to!, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.line 20:This is the location of function trap()
in the stack trace.line 36:Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap.
From looking at the code in source line 403, there is a
high probability that either the pointer access for
tp was messed up, or the array access was out of
bounds.line 52:The pointer looks suspicious, but happens to be a valid
address.line 56:However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
tp->t_line refers to the line discipline of
the console device here, which must be a rather small integer
number.)Debugging a Crash Dump with DDDExamining a kernel crash dump with a graphical debugger like
ddd is also possible. Add the
option to the ddd command line you would use
normally. For example;&prompt.root; ddd -k /var/crash/kernel.0 /var/crash/vmcore.0You should then be able to go about looking at the crash dump using
ddd's graphical interface.Post-Mortem Analysis of a DumpWhat do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using config -g? Not
everything is lost here. Do not panic!Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.Go to your kernel config directory
(/usr/src/sys/arch/conf)
and edit your configuration file. Uncomment (or add, if it does not
exist) the following linemakeoptions DEBUG=-g #Build kernel with gdb(1) debug symbolsRebuild the kernel. Due to the time stamp change on the Makefile,
there will be some other object files rebuild, for example
trap.o. With a bit of luck, the added
option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the &man.size.1; command. If there is a
mismatch, you probably need to give up here.Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the gdb
session until you know enough.All this is not guaranteed to work, but it will do it fine in most
cases.On-Line Kernel Debugging Using DDBWhile gdb as an off-line debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-stepping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like gdb.To configure your kernel to include DDB, add the option line
options DDB
to your config file, and rebuild. (See The FreeBSD Handbook for details on
+ url="../handbook/index.html">The FreeBSD Handbook for details on
configuring the FreeBSD kernel.If you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (options BREAK_TO_DEBUGGER
in the kernel config file). It is not the default since there are a lot
of crappy serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.The DDB commands roughly resemble some gdb
commands. The first thing you probably need to do is to set a
breakpoint:b function-nameb addressNumbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
a-f need to be preceded with 0x
(this is optional for other numbers). Simple expressions are allowed,
for example: function-name + 0x103.To continue the operation of an interrupted kernel, simply
type:cTo get a stack trace, use:traceNote that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.If you want to remove a breakpoint, usedeldel address-expressionThe first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:show bTo single-step the kernel, try:sThis will step into functions, but you can make DDB trace them until
the matching return statement is reached by:nThis is different from gdb's
next statement; it is like gdb's
finish.To examine data from memory, use (for example):
x/wx 0xf0133fe0,40x/hd db_symtab_spacex/bc termbuf,10x/s stringbuf
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:x ,10Similarly, use
x/ia foofunc,10
to disassemble the first 0x10 instructions of
foofunc, and display them along with their offset
from the beginning of foofunc.To modify memory, use the write command:w/b termbuf 0xa 0xb 0w/w 0xf0010030 0 0The command modifier
(b/h/w)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.If you need to know the current registers, use:show regAlternatively, you can display a single register value by e.g.
p $eax
and modify it by:set $eax new-valueShould you need to call some kernel functions from DDB, simply
say:call func(arg1, arg2, ...)The return value will be printed.For a &man.ps.1; style summary of all running processes, use:psNow you have examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:panicThis will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with gdb. This command
usually must be followed by another continue
statement.call boot(0)Which might be a good way to cleanly shut down the running system,
sync() all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.call cpu_reset()is the final way out of disaster and almost the same as hitting the
Big Red Button.If you need a short command summary, simply type:helpHowever, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.On-Line Kernel Debugging Using Remote GDBThis feature has been supported since FreeBSD 2.2, and it is
actually a very neat one.GDB has already supported remote debugging for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).You should configure the kernel in question with config
-g, include into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with strip -x, and boot it
using the boot option. Connect the serial line
of the target machine that has "flags 080" set on its sio device
to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:&prompt.user; gdb -k kernel
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
(kgdb)Initialize the remote debugging session (assuming the first serial
port is being used) by:(kgdb)target remote /dev/cuaa0Now, on the target host (the one that entered DDB right before even
starting the device probe), type:Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
db>gdbDDB will respond with:Next trap will enter GDB remote protocol modeEvery time you type gdb, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type s (step). Your hosting GDB
will now gain control over the target kernel:Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
(kgdb)You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.Debugging Loadable Modules Using GDBWhen debugging a panic that occurred within a module, or
using remote GDB against a machine that uses dynamic modules,
you need to tell GDB how to obtain symbol information for those
modules.First, you need to build the module(s) with debugging
information:&prompt.root; cd /sys/modules/linux
&prompt.root; make clean; make COPTS=-gIf you are using remote GDB, you can run
kldstat on the target machine to find out
where the module was loaded:&prompt.root; kldstat
Id Refs Address Size Name
1 4 0xc0100000 1c1678 kernel
2 1 0xc0a9e000 6000 linprocfs.ko
3 1 0xc0ad7000 2000 warp_saver.ko
4 1 0xc0adc000 11000 linux.koIf you are debugging a crash dump, you'll need to walk the
linker_files list, starting at
linker_files->tqh_first and following the
link.tqe_next pointers until you find the
entry with the filename you are looking for.
The address member of that entry is the load
address of the module.Next, you need to find out the offset of the text section
within the module:&prompt.root; objdump --section-headers /sys/modules/linux/linux.ko | grep text
3 .rel.text 000016e0 000038e0 000038e0 000038e0 2**2
10 .text 00007f34 000062d0 000062d0 000062d0 2**2The one you want is the .text section,
section 10 in the above example. The fourth hexadecimal field
(sixth field overall) is the offset of the text section within
the file. Add this offset to the load address of the module to
obtain the relocation address for the module's code. In our
example, we get 0xc0adc000 + 0x62d0 = 0xc0ae22d0. Use the
add-symbol-file command in GDB to tell the
debugger about the module:(kgdb)add-symbol-file /sys/modules/linux/linux.ko 0xc0ae22d0
add symbol table from file "/sys/modules/linux/linux.ko" at text_addr = 0xc0ae22d0?
(y or n) y
Reading symbols from /sys/modules/linux/linux.ko...done.
(kgdb)You should now have access to all the symbols in the
module.Debugging a Console DriverSince you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying at the Boot: prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.
diff --git a/en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml
index ca94063864..1598573616 100644
--- a/en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml
@@ -1,372 +1,372 @@
PCI DevicesThis chapter will talk about the FreeBSD mechanisms for
writing a device driver for a device on a PCI bus.Probe and AttachInformation here about how the PCI bus code iterates through
the unattached devices and see if a newly loaded kld will attach
to any of them./*
* Simple KLD to play with the PCI functions.
*
* Murray Stokely
*/
#define MIN(a,b) (((a) < (b)) ? (a) : (b))
#include <sys/types.h>
#include <sys/module.h>
#include <sys/systm.h> /* uprintf */
#include <sys/errno.h>
#include <sys/param.h> /* defines used in kernel.h */
#include <sys/kernel.h> /* types used in module initialization */
#include <sys/conf.h> /* cdevsw struct */
#include <sys/uio.h> /* uio struct */
#include <sys/malloc.h>
#include <sys/bus.h> /* structs, prototypes for pci bus stuff */
#include <pci/pcivar.h> /* For get_pci macros! */
/* Function prototypes */
d_open_t mypci_open;
d_close_t mypci_close;
d_read_t mypci_read;
d_write_t mypci_write;
/* Character device entry points */
static struct cdevsw mypci_cdevsw = {
mypci_open,
mypci_close,
mypci_read,
mypci_write,
noioctl,
nopoll,
nommap,
nostrategy,
"mypci",
36, /* reserved for lkms - /usr/src/sys/conf/majors */
nodump,
nopsize,
D_TTY,
-1
};
/* vars */
static dev_t sdev;
/* We're more interested in probe/attach than with
open/close/read/write at this point */
int
mypci_open(dev_t dev, int oflags, int devtype, struct proc *p)
{
int err = 0;
uprintf("Opened device \"mypci\" successfully.\n");
return(err);
}
int
mypci_close(dev_t dev, int fflag, int devtype, struct proc *p)
{
int err=0;
uprintf("Closing device \"mypci.\"\n");
return(err);
}
int
mypci_read(dev_t dev, struct uio *uio, int ioflag)
{
int err = 0;
uprintf("mypci read!\n");
return err;
}
int
mypci_write(dev_t dev, struct uio *uio, int ioflag)
{
int err = 0;
uprintf("mypci write!\n");
return(err);
}
/* PCI Support Functions */
/*
* Return identification string if this is device is ours.
*/
static int
mypci_probe(device_t dev)
{
uprintf("MyPCI Probe\n"
"Vendor ID : 0x%x\n"
"Device ID : 0x%x\n",pci_get_vendor(dev),pci_get_device(dev));
if (pci_get_vendor(dev) == 0x11c1) {
uprintf("We've got the Winmodem, probe successful!\n");
return 0;
}
return ENXIO;
}
/* Attach function is only called if the probe is successful */
static int
mypci_attach(device_t dev)
{
uprintf("MyPCI Attach for : deviceID : 0x%x\n",pci_get_vendor(dev));
sdev = make_dev(&mypci_cdevsw,
0,
UID_ROOT,
GID_WHEEL,
0600,
"mypci");
uprintf("Mypci device loaded.\n");
return ENXIO;
}
/* Detach device. */
static int
mypci_detach(device_t dev)
{
uprintf("Mypci detach!\n");
return 0;
}
/* Called during system shutdown after sync. */
static int
mypci_shutdown(device_t dev)
{
uprintf("Mypci shutdown!\n");
return 0;
}
/*
* Device suspend routine.
*/
static int
mypci_suspend(device_t dev)
{
uprintf("Mypci suspend!\n");
return 0;
}
/*
* Device resume routine.
*/
static int
mypci_resume(device_t dev)
{
uprintf("Mypci resume!\n");
return 0;
}
static device_method_t mypci_methods[] = {
/* Device interface */
DEVMETHOD(device_probe, mypci_probe),
DEVMETHOD(device_attach, mypci_attach),
DEVMETHOD(device_detach, mypci_detach),
DEVMETHOD(device_shutdown, mypci_shutdown),
DEVMETHOD(device_suspend, mypci_suspend),
DEVMETHOD(device_resume, mypci_resume),
{ 0, 0 }
};
static driver_t mypci_driver = {
"mypci",
mypci_methods,
0,
/* sizeof(struct mypci_softc), */
};
static devclass_t mypci_devclass;
DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);Additional Resources
- PCI
+ PCI
Special Interest GroupPCI System Architecture, Fourth Edition by
Tom Shanley, et al.Bus ResourcesFreeBSD provides an object-oriented mechanism for requesting
resources from a parent bus. Almost all devices will be a child
member of some sort of bus (PCI, ISA, USB, SCSI, etc) and these
devices need to acquire resources from their parent bus (such as
memory segments, interrupt lines, or DMA channels).Base Address RegistersTo do anything particularly useful with a PCI device you
will need to obtain the Base Address
Registers (BARs) from the PCI Configuration space.
The PCI-specific details of obtaining the BAR is abstracted in
the bus_alloc_resource() function.For example, a typical driver might have something similar
to this in the attach() function. : sc->bar0id = 0x10;
sc->bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &(sc->bar0id),
0, ~0, 1, RF_ACTIVE);
if (sc->bar0res == NULL) {
uprintf("Memory allocation of PCI base register 0 failed!\n");
error = ENXIO;
goto fail1;
}
sc->bar1id = 0x14;
sc->bar1res = bus_alloc_resource(dev, SYS_RES_MEMORY, &(sc->bar1id),
0, ~0, 1, RF_ACTIVE);
if (sc->bar1res == NULL) {
uprintf("Memory allocation of PCI base register 1 failed!\n");
error = ENXIO;
goto fail2;
}
sc->bar0_bt = rman_get_bustag(sc->bar0res);
sc->bar0_bh = rman_get_bushandle(sc->bar0res);
sc->bar1_bt = rman_get_bustag(sc->bar1res);
sc->bar1_bh = rman_get_bushandle(sc->bar1res);
Handles for each base address register are kept in the
softc structure so that they can be
used to write to the device later.These handles can then be used to read or write from the
device registers with the bus_space_*
functions. For example, a driver might contain a shorthand
function to read from a board specific register like this :
uint16_t
board_read(struct ni_softc *sc, uint16_t address) {
return bus_space_read_2(sc->bar1_bt, sc->bar1_bh, address);
}
Similarly, one could write to the registers with : void
board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
bus_space_write_2(sc->bar1_bt, sc->bar1_bh, address, value);
}
These functions exist in 8bit, 16bit, and 32bit versions
and you should use
bus_space_{read|write}_{1|2|4}
accordingly.InterruptsInterrupts are allocated from the object-oriented bus code
in a way similar to the memory resources. First an IRQ
resource must be allocated from the parent bus, and then the
interrupt handler must be setup to deal with this IRQ.Again, a sample from a device
attach() function says more than
words./* Get the IRQ resource */
sc->irqid = 0x0;
sc->irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &(sc->irqid),
0, ~0, 1, RF_SHAREABLE | RF_ACTIVE);
if (sc->irqres == NULL) {
uprintf("IRQ allocation failed!\n");
error = ENXIO;
goto fail3;
}
/* Now we should setup the interrupt handler */
error = bus_setup_intr(dev, sc->irqres, INTR_TYPE_MISC,
my_handler, sc, &(sc->handler));
if (error) {
printf("Couldn't set up irq\n");
goto fail4;
}
sc->irq_bt = rman_get_bustag(sc->irqres);
sc->irq_bh = rman_get_bushandle(sc->irqres);
DMAOn the PC, peripherals that want to do bus-mastering DMA
must deal with physical addresses. This is a problem since
FreeBSD uses virtual memory and deals almost exclusively with
virtual addresses. Fortunately, there is a function,
vtophys() to help.#include <vm/vm.h>
#include <vm/pmap.h>
#define vtophys(virtual_address) (...)
The solution is a bit different on the alpha however, and
what we really want is a function called
vtobus().#if defined(__alpha__)
#define vtobus(va) alpha_XXX_dmamap((vm_offset_t)va)
#else
#define vtobus(va) vtophys(va)
#endif
Deallocating ResourcesIt's very important to deallocate all of the resources
that were allocated during attach().
Care must be taken to deallocate the correct stuff even on a
failure condition so that the system will remain useable while
your driver dies.
diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
index c15c2ce893..29b376f578 100644
--- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
@@ -1,400 +1,400 @@
Source Tree Guidelines and PoliciesContributed by &a.phk;.This chapter documents various guidelines and policies in force for
the FreeBSD source tree.MAINTAINER on Makefilesports maintainerJune 1996.If a particular portion of the FreeBSD distribution is being
maintained by a person or group of persons, they can communicate this
fact to the world by adding a
MAINTAINER= email-addresses
line to the Makefiles covering this portion of the
source tree.The semantics of this are as follows:The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answer problem reports
pertaining to that piece of the code, and in the case of contributed
software, for tracking new versions, as appropriate.Changes to directories which have a maintainer defined shall be sent
to the maintainer for review before being committed. Only if the
maintainer does not respond for an unacceptable period of time, to
several emails, will it be acceptable to commit changes without review
by the maintainer. However, it is suggested that you try and have the
changes reviewed by someone else if at all possible.It is of course not acceptable to add a person or group as
maintainer unless they agree to assume this duty. On the other hand it
doesn't have to be a committer and it can easily be a group of
people.Contributed Softwarecontributed softwareContributed by &a.phk; and &a.obrien;. June 1996.Some parts of the FreeBSD distribution consist of software that is
actively being maintained outside the FreeBSD project. For historical
reasons, we call this contributed software. Some
examples are perl, gcc and patch.Over the last couple of years, various methods have been used in
dealing with this type of software and all have some number of
advantages and drawbacks. No clear winner has emerged.Since this is the case, after some debate one of these methods has
been selected as the official method and will be required
for future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on this
model over time, as it has significant advantages over the old method,
including the ability to easily obtain diffs relative to the
official versions of the source by everyone (even without
cvs access). This will make it significantly easier to return changes
to the primary developers of the contributed software.Ultimately, however, it comes down to the people actually doing the
work. If using this model is particularly unsuited to the package being
dealt with, exceptions to these rules may be granted only with the
approval of the core team and with the general consensus of the other
developers. The ability to maintain the package in the future will be a
key issue in the decisions.Because of some unfortunate design limitations with the RCS file
format and CVS's use of vendor branches, minor, trivial and/or
cosmetic changes are strongly discouraged on
files that are still tracking the vendor branch. Spelling
fixes are explicitly included here under the
cosmetic category and are to be avoided for files with
revision 1.1.x.x. The repository bloat impact from a single character
change can be rather dramatic.The Tcl embedded programming
language will be used as example of how this model works:src/contrib/tcl contains the source as
distributed by the maintainers of this package. Parts that are entirely
not applicable for FreeBSD can be removed. In the case of Tcl, the
mac, win and
compat subdirectories were eliminated before the
importsrc/lib/libtcl contains only a "bmake style"
Makefile that uses the standard
bsd.lib.mk makefile rules to produce the library
and install the documentation.src/usr.bin/tclsh contains only a bmake style
Makefile which will produce and install the
tclsh program and its associated man-pages using the
standard bsd.prog.mk rules.src/tools/tools/tcl_bmake contains a couple of
shell-scripts that can be of help when the tcl software needs updating.
These are not part of the built or installed software.The important thing here is that the
src/contrib/tcl directory is created according to
the rules: It is supposed to contain the sources as distributed (on a
proper CVS vendor-branch and without RCS keyword expansion) with as few
FreeBSD-specific changes as possible. The 'easy-import' tool on
freefall will assist in doing the import, but if there are any doubts on
how to go about it, it is imperative that you ask first and not blunder
ahead and hope it works out. CVS is not forgiving of
import accidents and a fair amount of effort is required to back out
major mistakes.Because of the previously mentioned design limitations with CVS's
vendor branches, it is required that official patches from
the vendor be applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should never
be patched into the FreeBSD checked out version and "committed", as this
destroys the vendor branch coherency and makes importing future versions
rather difficult as there will be conflicts.Since many packages contain files that are meant for compatibility
with other architectures and environments that FreeBSD, it is
permissible to remove parts of the distribution tree that are of no
interest to FreeBSD in order to save space. Files containing copyright
notices and release-note kind of information applicable to the remaining
files shall not be removed.If it seems easier, the bmakeMakefiles can be produced from the dist tree
automatically by some utility, something which would hopefully make it
even easier to upgrade to a new version. If this is done, be sure to
check in such utilities (as necessary) in the
src/tools directory along with the port itself so
that it is available to future maintainers.In the src/contrib/tcl level directory, a file
called FREEBSD-upgrade should be added and it
should states things like:Which files have been left outWhere the original distribution was obtained from and/or the
official master site.Where to send patches back to the original authorsPerhaps an overview of the FreeBSD-specific changes that have
been made.However, please do not import FREEBSD-upgrade
with the contributed source. Rather you should cvs add
FREEBSD-upgrade ; cvs ci after the initial import. Example
wording from src/contrib/cpio is below:This directory contains virgin sources of the original distribution files
on a "vendor" branch. Do not, under any circumstances, attempt to upgrade
the files in this directory via patches and a cvs commit. New versions or
official-patch versions must be imported. Please remember to import with
"-ko" to prevent CVS from corrupting any vendor RCS Ids.
For the import of GNU cpio 2.4.2, the following files were removed:
INSTALL cpio.info mkdir.c
Makefile.in cpio.texi mkinstalldirs
To upgrade to a newer version of cpio, when it is available:
1. Unpack the new version into an empty directory.
[Do not make ANY changes to the files.]
2. Remove the files listed above and any others that don't apply to
FreeBSD.
3. Use the command:
cvs import -ko -m 'Virgin import of GNU cpio v<version>' \
src/contrib/cpio GNU cpio_<version>
For example, to do the import of version 2.4.2, I typed:
cvs import -ko -m 'Virgin import of GNU v2.4.2' \
src/contrib/cpio GNU cpio_2_4_2
4. Follow the instructions printed out in step 3 to resolve any
conflicts between local FreeBSD changes and the newer version.
Do not, under any circumstances, deviate from this procedure.
To make local changes to cpio, simply patch and commit to the main
branch (aka HEAD). Never make local changes on the GNU branch.
All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
inclusion in the next vendor release.
obrien@FreeBSD.org - 30 March 1997Encumbered FilesIt might occasionally be necessary to include an encumbered file in
the FreeBSD source tree. For example, if a device requires a small
piece of binary code to be loaded to it before the device will operate,
and we do not have the source to that code, then the binary file is said
to be encumbered. The following policies apply to including encumbered
files in the FreeBSD source tree.Any file which is interpreted or executed by the system CPU(s)
and not in source format is encumbered.Any file with a license more restrictive than BSD or GNU is
encumbered.A file which contains downloadable binary data for use by the
hardware is not encumbered, unless (1) or (2) apply to it. It must
be stored in an architecture neutral ASCII format (file2c or
uuencoding is recommended).Any encumbered file requires specific approval from the
- Core team before it is added to the
+ Core team before it is added to the
CVS repository.Encumbered files go in src/contrib or
src/sys/contrib.The entire module should be kept together. There is no point in
splitting it, unless there is code-sharing with non-encumbered
code.Object files are named
arch/filename.o.uu>.Kernel files;Should always be referenced in
conf/files.* (for build simplicity).Should always be in LINT, but the
- Core team decides per case if it
+ Core team decides per case if it
should be commented out or not. The
- Core team can, of course, change
+ Core team can, of course, change
their minds later on.The Release Engineer
decides whether or not it goes in to the release.User-land files;core team
- The Core team decides if
+ The Core team decides if
the code should be part of make world.release engineer
- The Release Engineer
+ The Release Engineer
decides if it goes in to the release.Shared LibrariesContributed by &a.asami;, &a.peter;, and &a.obrien; 9
December 1996.If you are adding shared library support to a port or other piece of
software that doesn't have one, the version numbers should follow these
rules. Generally, the resulting numbers will have nothing to do with
the release version of the software.The three principles of shared library building are:Start from 1.0If there is a change that is backwards compatible, bump minor
number (note that ELF systems ignore the minor number)If there is an incompatible change, bump major numberFor instance, added functions and bugfixes result in the minor
version number being bumped, while deleted functions, changed function
call syntax etc. will force the major version number to change.Stick to version numbers of the form major.minor
(x.y). Our a.out
dynamic linker does not handle version numbers of the form
x.y.z
well. Any version number after the y
(ie. the third digit) is totally ignored when comparing shared lib
version numbers to decide which library to link with. Given two shared
libraries that differ only in the micro revision,
ld.so will link with the higher one. Ie: if you link
with libfoo.so.3.3.3, the linker only records
3.3 in the headers, and will link with anything
starting with
libfoo.so.3.(anything >=
3).(highest
available).ld.so will always use the highest
minor revision. Ie: it will use
libc.so.2.2 in preference to
libc.so.2.0, even if the program was initially
linked with libc.so.2.0.In addition, our ELF dynamic linker does not handle minor version
numbers at all. However, one should still specify a major and minor
version number as our Makefiles "do the right thing"
based on the type of system.For non-port libraries, it is also our policy to change the shared
library version number only once between releases. In addition, it is
our policy to change the major shared library version number only once
between major OS releases. Ie: X.0 to (X+1).0. When you make a
change to a system library that requires the version number to be
bumped, check the Makefile's commit logs. It is the
responsibility of the committer to ensure that the first such change
since the release will result in the shared library version number in
the Makefile to be updated, and any subsequent
changes will not.
diff --git a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
index d9ff3c872a..6de1cbd200 100644
--- a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
@@ -1,514 +1,514 @@
Secure ProgrammingThis chapter was written by &a.murray;.SynopsisThis chapter describes some of the security issues that
have plagued Unix programmers for decades and some of the new
tools available to help programmers avoid writing exploitable
code.Secure Design
MethodologyWriting secure applications takes a very scrutinous and
pessimistic outlook on life. Applications should be run with
the principle of least privilege so that no
process is ever running with more than the bare minimum access
that it needs to accomplish its function. Previously tested
code should be reused whenever possible to avoid common
mistakes that others may have already fixed.One of the pitfalls of the Unix environment is how easy it
is to make assumptions about the sanity of the environment.
Applications should never trust user input (in all its forms),
system resources, inter-process communication, or the timing of
events. Unix processes do not execute synchronously so logical
operations are rarely atomic.Buffer OverflowsBuffer Overflows have been around since the very
beginnings of the Von-Neuman architecture.
buffer overflowVon-Neuman
They first gained widespread notoriety in 1988 with the Morris
Internet worm. Unfortunately, the same basic attack remains
Morris Internet worm
effective today. Of the 17 CERT security advisories of 1999, 10
CERTsecurity advisories
of them were directly caused by buffer-overflow software bugs.
By far the most common type of buffer overflow attack is based
on corrupting the stack.stackargumentsMost modern computer systems use a stack to pass arguments
to procedures and to store local variables. A stack is a last
in first out (LIFO) buffer in the high memory area of a process
image. When a program invokes a function a new "stack frame" is
LIFOprocess imagestack pointer
created. This stack frame consists of the arguments passed to
the function as well as a dynamic amount of local variable
space. The "stack pointer" is a register that holds the current
stack framestack pointer
location of the top of the stack. Since this value is
constantly changing as new values are pushed onto the top of the
stack, many implementations also provide a "frame pointer" that
is located near the beginning of a stack frame so that local
variables can more easily be addressed relative to this
value. The return address for function
frame pointerprocess imageframe pointerreturn addressstack-overflow
calls is also stored on the stack, and this is the cause of
stack-overflow exploits since overflowing a local variable in a
function can overwrite the return address of that function,
potentially allowing a malicious user to execute any code he or
she wants.Although stack-based attacks are by far the most common,
it would also be possible to overrun the stack with a heap-based
(malloc/free) attack.The C programming language does not perform automatic
bounds checking on arrays or pointers as many other languages
do. In addition, the standard C library is filled with a
handful of very dangerous functions.strcpy(char *dest, const char
*src)May overflow the dest bufferstrcat(char *dest, const char
*src)May overflow the dest buffergetwd(char *buf)May overflow the buf buffergets(char *s)May overflow the s buffer[vf]scanf(const char *format,
...)May overflow its arguments.realpath(char *path, char
resolved_path[])May overflow the path buffer[v]sprintf(char *str, const char
*format, ...)May overflow the str buffer.Example Buffer OverflowThe following example code contains a buffer overflow
designed to overwrite the return address and skip the
instruction immediately following the function call. (Inspired
by )#include stdio.h
void manipulate(char *buffer) {
char newbuffer[80];
strcpy(newbuffer,buffer);
}
int main() {
char ch,buffer[4096];
int i=0;
while ((buffer[i++] = getchar()) != '\n') {};
i=1;
manipulate(buffer);
i=2;
printf("The value of i is : %d\n",i);
return 0;
}Let us examine what the memory image of this process would
look like if we were to input 160 spaces into our little program
before hitting return.[XXX figure here!]Obviously more malicious input can be devised to execute
actual compiled instructions (such as exec(/bin/sh)).Avoiding Buffer OverflowsThe most straightforward solution to the problem of
stack-overflows is to always use length restricted memory and
string copy functions. strncpy and
strncat are part of the standard C library.
string copy functionsstrncpystring copy functionsstrncat
These functions accept a length value as a parameter which
should be no larger than the size of the destination buffer.
These functions will then copy up to `length' bytes from the
source to the destination. However there are a number of
problems with these functions. Neither function guarantees NUL
termination if the size of the input buffer is as large as the
NUL termination
destination. The length parameter is also used inconsistently
between strncpy and strncat so it is easy for programmers to get
confused as to their proper usage. There is also a significant
performance loss compared to strcpy when
copying a short string into a large buffer since
strncpy NUL fills up the size
specified.In OpenBSD, another memory copy implementation has been
OpenBSD
created to get around these problem. The
strlcpy and strlcat
functions guarantee that they will always null terminate the
destination string when given a non-zero length argument. For
more information about these functions see . The OpenBSD strlcpy and
strlcat instructions have been in FreeBSD
since 3.3.string copy functionsstrlcpystring copy functionsstrlcatCompiler based run-time bounds checkingbounds checkingcompiler-basedUnfortunately there is still a very large assortment of
code in public use which blindly copies memory around without
using any of the bounded copy routines we just discussed.
Fortunately, there is another solution. Several compiler
add-ons and libraries exist to do Run-time bounds checking in
C/C++.StackGuardgccStackGuard is one such add-on that is implemented as a
small patch to the gcc code generator. From the StackGuard
website, http://immunix.org/stackguard.html :
"StackGuard detects and defeats stack
smashing attacks by protecting the return address on the stack
from being altered. StackGuard places a "canary" word next to
the return address when a function is called. If the canary
word has been altered when the function returns, then a stack
smashing attack has been attempted, and the program responds
by emitting an intruder alert into syslog, and then
halts."
"StackGuard is implemented as a small patch
to the gcc code generator, specifically the function_prolog()
and function_epilog() routines. function_prolog() has been
enhanced to lay down canaries on the stack when functions
start, and function_epilog() checks canary integrity when the
function exits. Any attempt at corrupting the return address
is thus detected before the function
returns."
buffer overflowRecompiling your application with StackGuard is an
effective means of stopping most buffer-overflow attacks, but
it can still be compromised.Library based run-time bounds checkingbounds checkinglibrary-basedCompiler-based mechanisms are completely useless for
binary-only software for which you cannot recompile. For
these situations there are a number of libraries which
re-implement the unsafe functions of the C-library
(strcpy, fscanf,
getwd, etc..) and ensure that these
functions can never write past the stack pointer.libsafelibverifylibparnoiaUnfortunately these library-based defenses have a number
of shortcomings. These libraries only protect against a very
small set of security related issues and they neglect to fix
the actual problem. These defenses may fail if the
application was compiled with -fomit-frame-pointer. Also, the
LD_PRELOAD and LD_LIBRARY_PATH environment variables can be
overwritten/unset by the user.SetUID issuesseteuidThere are at least 6 different IDs associated with any
given process. Because of this you have to be very careful with
the access that your process has at any given time. In
particular, all seteuid applications should give up their
privileges as soon as it is no longer required.user IDsreal user IDuser IDseffective user IDThe real user ID can only be changed by a superuser
process. The login program sets this
when a user initially logs in and it is seldom changed.The effective user ID is set by the
exec() functions if a program has its
seteuid bit set. An application can call
seteuid() at any time to set the effective
user ID to either the real user ID or the saved set-user-ID.
When the effective user ID is set by exec()
functions, the previous value is saved in the saved set-user-ID.Limiting your program's environmentchroot()The traditional method of restricting a process
is with the chroot() system call. This
system call changes the root directory from which all other
paths are referenced for a process and any child processes. For
this call to succeed the process must have execute (search)
permission on the directory being referenced. The new
environment does not actually take effect until you
chdir() into your new environment. It
should also be noted that a process can easily break out of a
chroot environment if it has root privilege. This could be
accomplished by creating device nodes to read kernel memory,
attaching a debugger to a process outside of the jail, or in
many other creative ways.The behavior of the chroot() system
call can be controlled somewhat with the
kern.chroot_allow_open_directories sysctl
variable. When this value is set to 0,
chroot() will fail with EPERM if there are
any directories open. If set to the default value of 1, then
chroot() will fail with EPERM if there are
any directories open and the process is already subject to a
chroot() call. For any other value, the
check for open directories will be bypassed completely.FreeBSD's jail functionalityjailThe concept of a Jail extends upon the
chroot() by limiting the powers of the
superuser to create a true `virtual server'. Once a prison is
setup all network communication must take place through the
specified IP address, and the power of "root privilege" in this
jail is severely constrained.While in a prison, any tests of superuser power within the
kernel using the suser() call will fail.
However, some calls to suser() have been
changed to a new interface suser_xxx().
This function is responsible for recognizing or denying access
to superuser power for imprisoned processes.A superuser process within a jailed environment has the
power to : Manipulate credential with
setuid, seteuid,
setgid, setegid,
setgroups, setreuid,
setregid, setloginSet resource limits with setrlimitModify some sysctl nodes
(kern.hostname)chroot()Set flags on a vnode:
chflags,
fchflagsSet attributes of a vnode such as file
permission, owner, group, size, access time, and modification
time.Bind to privileged ports in the Internet
domain (ports < 1024)Jail is a very useful tool for
running applications in a secure environment but it does have
some shortcomings. Currently, the IPC mechanisms have not been
converted to the suser_xxx so applications
such as MySQL cannot be run within a jail. Superuser access
may have a very limited meaning within a jail, but there is
no way to specify exactly what "very limited" means.POSIX.1e Process CapabilitiesPOSIX.1e Process CapabilitiesTrustedBSDPosix has released a working draft that adds event
auditing, access control lists, fine grained privileges,
information labeling, and mandatory access control.This is a work in progress and is the focus of the TrustedBSD project. Some
+ url="http://www.trustedbsd.org/">TrustedBSD project. Some
of the initial work has been committed to FreeBSD-current
(cap_set_proc(3)).TrustAn application should never assume that anything about the
users environment is sane. This includes (but is certainly not
limited to) : user input, signals, environment variables,
resources, IPC, mmaps, the file system working directory, file
descriptors, the # of open files, etc.positive filteringdata validationYou should never assume that you can catch all forms of
invalid input that a user might supply. Instead, your
application should use positive filtering to only allow a
specific subset of inputs that you deem safe. Improper data
validation has been the cause of many exploits, especially with
CGI scripts on the world wide web. For filenames you need to be
extra careful about paths ("../", "/"), symbolic links, and
shell escape characters.Perl Taint modePerl has a really cool feature called "Taint" mode which
can be used to prevent scripts from using data derived outside
the program in an unsafe way. This mode will check command line
arguments, environment variables, locale information, the
results of certain syscalls (readdir(),
readlink(),
getpwxxx(), and all file input.Race ConditionsA race condition is anomalous behavior caused by the
unexpected dependence on the relative timing of events. In
other words, a programmer incorrectly assumed that a particular
event would always happen before another.race conditionssignalsrace conditionsaccess checksrace conditionsfile opensSome of the common causes of race conditions are signals,
access checks, and file opens. Signals are asynchronous events
by nature so special care must be taken in dealing with them.
Checking access with access(2) then
open(2) is clearly non-atomic. Users can
move files in between the two calls. Instead, privileged
applications should seteuid() and then call
open() directly. Along the same lines, an
application should always set a proper umask before
open() to obviate the need for spurious
chmod() calls.
diff --git a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
index a939990c47..45c24ff136 100644
--- a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
@@ -1,2298 +1,2298 @@
Programming ToolsThis chapter was written by &a.jraynard;.
Modifications for the Developers' Handbook by &a.murray;.
SynopsisThis document is an introduction to using some of the
programming tools supplied with FreeBSD, although much of it
will be applicable to many other versions of Unix. It does
not attempt to describe coding in any
detail. Most of the document assumes little or no previous
programming knowledge, although it is hoped that most
programmers will find something of value in it.IntroductionFreeBSD offers an excellent development environment.
Compilers for C, C++, and Fortran and an assembler come with the
basic system, not to mention a Perl interpreter and classic Unix
tools such as sed and awk.
If that is not enough, there are many more compilers and
interpreters in the Ports collection. FreeBSD is very
compatible with standards such as POSIX and
ANSI C, as well with its own BSD heritage, so
it is possible to write applications that will compile and run
with little or no modification on a wide range of
platforms.However, all this power can be rather overwhelming at
first if you've never written programs on a Unix platform
before. This document aims to help you get up and running,
without getting too deeply into more advanced topics. The
intention is that this document should give you enough of the
basics to be able to make some sense of the
documentation.Most of the document requires little or no knowledge of
programming, although it does assume a basic competence with
using Unix and a willingness to learn!Introduction to ProgrammingA program is a set of instructions that tell the computer
to do various things; sometimes the instruction it has to
perform depends on what happened when it performed a previous
instruction. This section gives an overview of the two main
ways in which you can give these instructions, or
commands as they are usually called. One way
uses an interpreter, the other a
compiler. As human languages are too
difficult for a computer to understand in an unambiguous way,
commands are usually written in one or other languages specially
designed for the purpose.InterpretersWith an interpreter, the language comes as an environment,
where you type in commands at a prompt and the environment
executes them for you. For more complicated programs, you can
type the commands into a file and get the interpreter to load
the file and execute the commands in it. If anything goes
wrong, many interpreters will drop you into a debugger to help
you track down the problem.The advantage of this is that you can see the results of
your commands immediately, and mistakes can be corrected
readily. The biggest disadvantage comes when you want to
share your programs with someone. They must have the same
interpreter, or you must have some way of giving it to them,
and they need to understand how to use it. Also users may not
appreciate being thrown into a debugger if they press the
wrong key! From a performance point of view, interpreters can
use up a lot of memory, and generally do not generate code as
efficiently as compilers.In my opinion, interpreted languages are the best way to
start if you have not done any programming before. This kind
of environment is typically found with languages like Lisp,
Smalltalk, Perl and Basic. It could also be argued that the
Unix shell (sh, csh) is itself an
interpreter, and many people do in fact write shell
scripts to help with various
housekeeping tasks on their machine. Indeed, part
of the original Unix philosophy was to provide lots of small
utility programs that could be linked together in shell
scripts to perform useful tasks.Interpreters available with FreeBSDHere is a list of interpreters that are available as
FreeBSD
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">FreeBSD
packages, with a brief discussion of some of the
more popular interpreted languages.To get one of these packages, all you need to do is to
click on the hotlink for the package, then run&prompt.root; pkg_add package name>as root. Obviously, you will need to have a fully
functional FreeBSD 2.1.0 or later system for the package to
work!BASICShort for Beginner's All-purpose Symbolic
Instruction Code. Developed in the 1950s for teaching
University students to program and provided with every
self-respecting personal computer in the 1980s,
BASIC has been the first programming
language for many programmers. It's also the foundation
for Visual Basic.The Bywater
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/lang/bwbasic-2.10.tgz">Bywater
Basic Interpreter and the Phil
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/lang/pbasic-2.0.tgz">Phil
Cockroft's Basic Interpreter (formerly Rabbit
Basic) are available as FreeBSD
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">FreeBSD
packages.LispA language that was developed in the late 1950s as
an alternative to the number-crunching
languages that were popular at the time. Instead of
being based on numbers, Lisp is based on lists; in fact
the name is short for List Processing.
Very popular in AI (Artificial Intelligence)
circles.Lisp is an extremely powerful and sophisticated
language, but can be rather large and unwieldy.FreeBSD has GNU
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/gcl-2.0.tgz">GNU
Common Lisp available as a package.PerlVery popular with system administrators for writing
scripts; also often used on World Wide Web servers for
writing CGI scripts.The latest version (version 5) comes with FreeBSD.SchemeA dialect of Lisp that is rather more compact and
cleaner than Common Lisp. Popular in Universities as it
is simple enough to teach to undergraduates as a first
language, while it has a high enough level of
abstraction to be used in research work.FreeBSD has packages of the Elk
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/lang/elk-3.0.tgz">Elk
Scheme Interpreter, the MIT
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/lang/mit-scheme-7.3.tgz">MIT
Scheme Interpreter and the SCM
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/lang/scm-4e1.tgz">SCM
Scheme Interpreter.IconThe
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/lang/icon-9.0.tgz">The
Icon Programming Language.LogoBrian
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/lang/ucblogo-3.3.tgz">Brian
Harvey's LOGO Interpreter.PythonThe
+ URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/lang/python-1.2.tgz">The
Python Object-Oriented Programming
LanguageCompilersCompilers are rather different. First of all, you write
your code in a file (or files) using an editor. You then run
the compiler and see if it accepts your program. If it did
not compile, grit your teeth and go back to the editor; if it
did compile and gave you a program, you can run it either at a
shell command prompt or in a debugger to see if it works
properly.
If you run it in the shell, you may get a core
dump.Obviously, this is not quite as direct as using an
interpreter. However it allows you to do a lot of things
which are very difficult or even impossible with an
interpreter, such as writing code which interacts closely with
the operating system—or even writing your own operating
system! It's also useful if you need to write very efficient
code, as the compiler can take its time and optimise the code,
which would not be acceptable in an interpreter. And
distributing a program written for a compiler is usually more
straightforward than one written for an interpreter—you
can just give them a copy of the executable, assuming they
have the same operating system as you.Compiled languages include Pascal, C and C++. C and C++
are rather unforgiving languages, and best suited to more
experienced programmers; Pascal, on the other hand, was
designed as an educational language, and is quite a good
language to start with. FreeBSD doesn't include Pascal
support in the base system, but the GNU Pascal Compiler (gpc)
is available in the ports collection.As the edit-compile-run-debug cycle is rather tedious when
using separate programs, many commercial compiler makers have
produced Integrated Development Environments
(IDEs for short). FreeBSD does not include
an IDE in the base system, but devel/kdevelop is
available in the ports tree and many use
Emacs for this purpose. Using
Emacs as an IDE is discussed in
.Compiling with ccThis section deals only with the GNU compiler for C and C++,
since that comes with the base FreeBSD system. It can be
invoked by either cc or gcc. The
details of producing a program with an interpreter vary
considerably between interpreters, and are usually well covered
in the documentation and on-line help for the
interpreter.Once you've written your masterpiece, the next step is to
convert it into something that will (hopefully!) run on FreeBSD.
This usually involves several steps, each of which is done by a
separate program.Pre-process your source code to remove comments and do
other tricks like expanding macros in C.Check the syntax of your code to see if you have obeyed
the rules of the language. If you have not, it will
complain!Convert the source code into assembly
language—this is very close to machine code, but still
understandable by humans. Allegedly.
To be strictly accurate, cc converts the
source code into its own, machine-independent
p-code instead of assembly language at
this stage.Convert the assembly language into machine
code—yep, we are talking bits and bytes, ones and
zeros here.Check that you have used things like functions and
global variables in a consistent way. For example, if you
have called a non-existent function, it will
complain.If you are trying to produce an executable from several
source code files, work out how to fit them all
together.Work out how to produce something that the system's
run-time loader will be able to load into memory and
run.Finally, write the executable on the file system.The word compiling is often used to refer to
just steps 1 to 4—the others are referred to as
linking. Sometimes step 1 is referred to as
pre-processing and steps 3-4 as
assembling.Fortunately, almost all this detail is hidden from you, as
cc is a front end that manages calling all these
programs with the right arguments for you; simply typing&prompt.user; cc foobar.c>will cause foobar.c to be compiled by all the
steps above. If you have more than one file to compile, just do
something like&prompt.user; cc foo.c bar.c>Note that the syntax checking is just that—checking
the syntax. It will not check for any logical mistakes you may
have made, like putting the program into an infinite loop, or
using a bubble sort when you meant to use a binary
sort.
In case you didn't know, a binary sort is an efficient
way of sorting things into order and a bubble sort
isn't.There are lots and lots of options for cc, which
are all in the man page. Here are a few of the most important
ones, with examples of how to use them.The output name of the file. If you do not use this
option, cc will produce an executable called
a.out.
The reasons for this are buried in the mists of
history.&prompt.user; cc foobar.c> executable is a.out>>
&prompt.user; cc -o foobar foobar.c> executable is foobar>>
Just compile the file, do not link it. Useful for toy
programs where you just want to check the syntax, or if
you are using a Makefile.&prompt.user; cc -c foobar.cThis will produce an object file (not an
executable) called foobar.o. This
can be linked together with other object files into an
executable.Create a debug version of the executable. This makes
the compiler put information into the executable about
which line of which source file corresponds to which
function call. A debugger can use this information to show
the source code as you step through the program, which is
very useful; the disadvantage is that
all this extra information makes the program much bigger.
Normally, you compile with while you
are developing a program and then compile a release
version without when you're
satisfied it works properly.&prompt.user; cc -g foobar.cThis will produce a debug version of the
program.
Note, we didn't use the flag
to specify the executable name, so we will get an
executable called a.out.
Producing a debug version called
foobar is left as an exercise for
the reader!Create an optimised version of the executable. The
compiler performs various clever tricks to try and produce
an executable that runs faster than normal. You can add a
number after the to specify a higher
level of optimisation, but this often exposes bugs in the
compiler's optimiser. For instance, the version of
cc that comes with the 2.1.0 release of
FreeBSD is known to produce bad code with the
option in some circumstances.Optimisation is usually only turned on when compiling
a release version.&prompt.user; cc -O -o foobar foobar.cThis will produce an optimised version of
foobar.The following three flags will force cc
to check that your code complies to the relevant international
standard, often referred to as the ANSI
standard, though strictly speaking it is an
ISO standard.Enable all the warnings which the authors of
cc believe are worthwhile. Despite the
name, it will not enable all the warnings
cc is capable of.Turn off most, but not all, of the
non-ANSI C features provided by
cc. Despite the name, it does not
guarantee strictly that your code will comply to the
standard.Turn off allcc's non-ANSI C
features.Without these flags, cc will allow you to
use some of its non-standard extensions to the standard. Some
of these are very useful, but will not work with other
compilers—in fact, one of the main aims of the standard is
to allow people to write code that will work with any compiler
on any system. This is known as portable
code.Generally, you should try to make your code as portable as
possible, as otherwise you may have to completely re-write the
program later to get it to work somewhere else—and who
knows what you may be using in a few years time?&prompt.user; cc -Wall -ansi -pedantic -o foobar foobar.cThis will produce an executable foobar
after checking foobar.c for standard
compliance.Specify a function library to be used during when
linking.The most common example of this is when compiling a
program that uses some of the mathematical functions in C.
Unlike most other platforms, these are in a separate
library from the standard C one and you have to tell the
compiler to add it.The rule is that if the library is called
libsomething.a,
you give cc the argument
.
For example, the math library is
libm.a, so you give
cc the argument .
A common gotcha with the math library is
that it has to be the last library on the command
line.&prompt.user; cc -o foobar foobar.c -lmThis will link the math library functions into
foobar.If you are compiling C++ code, you need to add
, or if
you are using FreeBSD 2.2 or later, to the command line
argument to link the C++ library functions.
Alternatively, you can run c++ instead
of cc, which does this for you.
c++ can also be invoked as
g++ on FreeBSD.&prompt.user; cc -o foobar foobar.cc -lg++For FreeBSD 2.1.6 and earlier>
&prompt.user; cc -o foobar foobar.cc -lstdc++For FreeBSD 2.2 and later>
&prompt.user; c++ -o foobar foobar.ccEach of these will both produce an executable
foobar from the C++ source file
foobar.cc. Note that, on Unix
systems, C++ source files traditionally end in
.C, .cxx or
.cc, rather than the
MS-DOS style
.cpp (which was already used for
something else). gcc used to rely on
this to work out what kind of compiler to use on the
source file; however, this restriction no longer applies,
so you may now call your C++ files
.cpp with impunity!Common cc Queries and ProblemsI am trying to write a program which uses the
sin() function and I get an error
like this. What does it mean?/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment
When using mathematical functions like
sin(), you have to tell
cc to link in the math library, like
so:&prompt.user; cc -o foobar foobar.c -lmAll right, I wrote this simple program to practice
using . All it does is raise 2.1 to
the power of 6.#include <stdio.h>
int main() {
float f;
f = pow(2.1, 6);
printf("2.1 ^ 6 = %f\n", f);
return 0;
}
and I compiled it as:&prompt.user; cc temp.c -lmlike you said I should, but I get this when I run
it:&prompt.user; ./a.out
2.1 ^ 6 = 1023.000000
This is not the right answer!
What is going on?When the compiler sees you call a function, it
checks if it has already seen a prototype for it. If it
has not, it assumes the function returns an
int, which is definitely not what you want
here.So how do I fix this?The prototypes for the mathematical functions are in
math.h. If you include this file,
the compiler will be able to find the prototype and it
will stop doing strange things to your
calculation!#include <math.h>
#include <stdio.h>
int main() {
...
After recompiling it as you did before, run
it:&prompt.user; ./a.out
2.1 ^ 6 = 85.766121
If you are using any of the mathematical functions,
always include
math.h and remember to link in the
math library.I compiled a file called
foobar.c and I cannot find an
executable called foobar. Where's
it gone?Remember, cc will call the
executable a.out unless you tell it
differently. Use the
option:&prompt.user; cc -o foobar foobar.cOK, I have an executable called
foobar, I can see it when I run
ls, but when I type in
foobar at the command prompt it tells
me there is no such file. Why can it not find
it?Unlike MS-DOS, Unix does not
look in the current directory when it is trying to find
out which executable you want it to run, unless you tell
it to. Either type ./foobar, which
means run the file called
foobar in the current
directory, or change your PATH
environment
variable so that it looks something likebin:/usr/bin:/usr/local/bin:.
The dot at the end means look in the current
directory if it is not in any of the
others.I called my executable test,
but nothing happens when I run it. What is going
on?Most Unix systems have a program called
test in /usr/bin
and the shell is picking that one up before it gets to
checking the current directory. Either type:&prompt.user; ./testor choose a better name for your program!I compiled my program and it seemed to run all right
at first, then there was an error and it said something
about core dumped. What does that
mean?The name core dump dates back
to the very early days of Unix, when the machines used
core memory for storing data. Basically, if the program
failed under certain conditions, the system would write
the contents of core memory to disk in a file called
core, which the programmer could
then pore over to find out what went wrong.Fascinating stuff, but what I am supposed to do
now?Use gdb to analyse the core (see
).When my program dumped core, it said something about
a segmentation fault. What's
that?This basically means that your program tried to
perform some sort of illegal operation on memory; Unix
is designed to protect the operating system and other
programs from rogue programs.Common causes for this are:Trying to write to a NULL
pointer, egchar *foo = NULL;
strcpy(foo, "bang!");
Using a pointer that hasn't been initialised,
egchar *foo;
strcpy(foo, "bang!");
The pointer will have some random value that,
with luck, will point into an area of memory that
isn't available to your program and the kernel will
kill your program before it can do any damage. If
you're unlucky, it'll point somewhere inside your
own program and corrupt one of your data structures,
causing the program to fail mysteriously.Trying to access past the end of an array,
egint bar[20];
bar[27] = 6;
Trying to store something in read-only memory,
egchar *foo = "My string";
strcpy(foo, "bang!");
Unix compilers often put string literals like
"My string" into read-only areas
of memory.Doing naughty things with
malloc() and
free(), egchar bar[80];
free(bar);
orchar *foo = malloc(27);
free(foo);
free(foo);
Making one of these mistakes will not always lead to
an error, but they are always bad practice. Some
systems and compilers are more tolerant than others,
which is why programs that ran well on one system can
crash when you try them on an another.Sometimes when I get a core dump it says
bus error. It says in my Unix
book that this means a hardware problem, but the
computer still seems to be working. Is this
true?No, fortunately not (unless of course you really do
have a hardware problem…). This is usually
another way of saying that you accessed memory in a way
you shouldn't have.This dumping core business sounds as though it could
be quite useful, if I can make it happen when I want to.
Can I do this, or do I have to wait until there's an
error?Yes, just go to another console or xterm, do&prompt.user; psto find out the process ID of your program, and
do&prompt.user; kill -ABRT pidwhere
pid is
the process ID you looked up.This is useful if your program has got stuck in an
infinite loop, for instance. If your program happens to
trap SIGABRT, there are several other
signals which have a similar effect.Alternatively, you can create a core dump from
inside your program, by calling the
abort() function. See the man page
of &man.abort.3; to learn more.If you want to create a core dump from outside your
program, but don't want the process to terminate, you
can use the gcore program. See the
man page of &man.gcore.1 for more information.MakeWhat is make?When you're working on a simple program with only one or
two source files, typing in&prompt.user; cc file1.c file2.cis not too bad, but it quickly becomes very tedious when
there are several files—and it can take a while to
compile, too.One way to get around this is to use object files and only
recompile the source file if the source code has changed. So
we could have something like:&prompt.user; cc file1.o file2.o … file37.c &hellipif we'd changed file37.c, but not any
of the others, since the last time we compiled. This may
speed up the compilation quite a bit, but doesn't solve the
typing problem.Or we could write a shell script to solve the typing
problem, but it would have to re-compile everything, making it
very inefficient on a large project.What happens if we have hundreds of source files lying
about? What if we're working in a team with other people who
forget to tell us when they've changed one of their source
files that we use?Perhaps we could put the two solutions together and write
something like a shell script that would contain some kind of
magic rule saying when a source file needs compiling. Now all
we need now is a program that can understand these rules, as
it's a bit too complicated for the shell.This program is called make. It reads
in a file, called a makefile, that
tells it how different files depend on each other, and works
out which files need to be re-compiled and which ones don't.
For example, a rule could say something like if
fromboz.o is older than
fromboz.c, that means someone must have
changed fromboz.c, so it needs to be
re-compiled. The makefile also has rules telling
make how to re-compile the source file,
making it a much more powerful tool.Makefiles are typically kept in the same directory as the
source they apply to, and can be called
makefile, Makefile
or MAKEFILE. Most programmers use the
name Makefile, as this puts it near the
top of a directory listing, where it can easily be
seen.
They don't use the MAKEFILE form
as block capitals are often used for documentation files
like README.Example of using makeHere's a very simple make file:foo: foo.c
cc -o foo foo.cIt consists of two lines, a dependency line and a creation
line.The dependency line here consists of the name of the
program (known as the target), followed
by a colon, then whitespace, then the name of the source file.
When make reads this line, it looks to see
if foo exists; if it exists, it compares
the time foo was last modified to the
time foo.c was last modified. If
foo does not exist, or is older than
foo.c, it then looks at the creation line
to find out what to do. In other words, this is the rule for
working out when foo.c needs to be
re-compiled.The creation line starts with a tab (press
the tab key) and then the command you would
type to create foo if you were doing it
at a command prompt. If foo is out of
date, or does not exist, make then executes
this command to create it. In other words, this is the rule
which tells make how to re-compile
foo.c.So, when you type make, it will
make sure that foo is up to date with
respect to your latest changes to foo.c.
This principle can be extended to
Makefiles with hundreds of
targets—in fact, on FreeBSD, it is possible to compile
the entire operating system just by typing make
world in the appropriate directory!Another useful property of makefiles is that the targets
don't have to be programs. For instance, we could have a make
file that looks like this:foo: foo.c
cc -o foo foo.c
install:
cp foo /home/meWe can tell make which target we want to make by
typing:&prompt.user; make targetmake will then only look at that target
and ignore any others. For example, if we type
make foo with the makefile above, make
will ignore the install target.If we just type make on its own,
make will always look at the first target and then stop
without looking at any others. So if we typed
make here, it will just go to the
foo target, re-compile
foo if necessary, and then stop without
going on to the install target.Notice that the install target doesn't
actually depend on anything! This means that the command on
the following line is always executed when we try to make that
target by typing make install. In this
case, it will copy foo into the user's
home directory. This is often used by application makefiles,
so that the application can be installed in the correct
directory when it has been correctly compiled.This is a slightly confusing subject to try and explain.
If you don't quite understand how make
works, the best thing to do is to write a simple program like
hello world and a make file like the one above
and experiment. Then progress to using more than one source
file, or having the source file include a header file. The
touch command is very useful here—it
changes the date on a file without you having to edit
it.Make and include-filesC code often starts with a list of files to include, for
example stdio.h. Some of these files are system-include
files, some of them are from the project you're now working
on:
#include <stdio.h>
#include "foo.h"
int main(....To make sure that this file is recompiled the moment
foo.h is changed, you have to add it in
your Makefile:foo: foo.c foo.hThe moment your project is getting bigger and you have
more and more own include-files to maintain, it will be a
pain to keep track of all include files and the files which
are depending on it. If you change an include-file but
forget to recompile all the files which are depending on
it, the results will be devastating. gcc
has an option to analyze your files and to produce a list
of include-files and their dependencies: .
If you add this to your Makefile:depend:
gcc -E -MM *.c > .dependand run make depend, the file
.depend will appear with a list of
object-files, C-files and the include-files:foo.o: foo.c foo.hIf you change foo.h, next time
you run make all files depending on
foo.h will be recompiled.Don't forget to run make depend each
time you add an include-file to one of your files.FreeBSD MakefilesMakefiles can be rather complicated to write. Fortunately,
BSD-based systems like FreeBSD come with some very powerful
ones as part of the system. One very good example of this is
the FreeBSD ports system. Here's the essential part of a
typical ports Makefile:MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/
DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
.include <bsd.port.mk>Now, if we go to the directory for this port and type
make, the following happens:A check is made to see if the source code for this
port is already on the system.If it isn't, an FTP connection to the URL in
MASTER_SITES is set up to download the
source.The checksum for the source is calculated and compared
it with one for a known, good, copy of the source. This
is to make sure that the source was not corrupted while in
transit.Any changes required to make the source work on
FreeBSD are applied—this is known as
patching.Any special configuration needed for the source is
done. (Many Unix program distributions try to work out
which version of Unix they are being compiled on and which
optional Unix features are present—this is where
they are given the information in the FreeBSD ports
scenario).The source code for the program is compiled. In
effect, we change to the directory where the source was
unpacked and do make—the
program's own make file has the necessary information to
build the program.We now have a compiled version of the program. If we
wish, we can test it now; when we feel confident about the
program, we can type make install.
This will cause the program and any supporting files it
needs to be copied into the correct location; an entry is
also made into a package database, so
that the port can easily be uninstalled later if we change
our mind about it.Now I think you'll agree that's rather impressive for a
four line script!The secret lies in the last line, which tells
make to look in the system makefile called
bsd.port.mk. It's easy to overlook this
line, but this is where all the clever stuff comes
from—someone has written a makefile that tells
make to do all the things above (plus a
couple of other things I didn't mention, including handling
any errors that may occur) and anyone can get access to that
just by putting a single line in their own make file!If you want to have a look at these system makefiles,
they're in /usr/share/mk, but it's
probably best to wait until you've had a bit of practice with
makefiles, as they are very complicated (and if you do look at
them, make sure you have a flask of strong coffee
handy!)More advanced uses of makeMake is a very powerful tool, and can
do much more than the simple example above shows.
Unfortunately, there are several different versions of
make, and they all differ considerably.
The best way to learn what they can do is probably to read the
documentation—hopefully this introduction will have
given you a base from which you can do this.The version of make that comes with FreeBSD is the
Berkeley make; there is a tutorial
for it in /usr/share/doc/psd/12.make. To
view it, do&prompt.user; zmore paper.ascii.gzin that directory.Many applications in the ports use GNU
make, which has a very good set of
info pages. If you have installed any of these
ports, GNU make will automatically
have been installed as gmake. It's also
available as a port and package in its own right.To view the info pages for GNU
make, you will have to edit the
dir file in the
/usr/local/info directory to add an entry
for it. This involves adding a line like * Make: (make). The GNU Make utility.to the file. Once you have done this, you can type
info and then select
make from the menu (or in
Emacs, do C-h
i).DebuggingThe DebuggerThe debugger that comes with FreeBSD is called
gdb (GNU
debugger). You start it up by typing&prompt.user; gdb prognamealthough most people prefer to run it inside
Emacs. You can do this by:M-x gdb RET progname RETUsing a debugger allows you to run the program under more
controlled circumstances. Typically, you can step through the
program a line at a time, inspect the value of variables,
change them, tell the debugger to run up to a certain point
and then stop, and so on. You can even attach to a program
that's already running, or load a core file to investigate why
the program crashed. It's even possible to debug the kernel,
though that's a little trickier than the user applications
we'll be discussing in this section.gdb has quite good on-line help, as
well as a set of info pages, so this section will concentrate
on a few of the basic commands.Finally, if you find its text-based command-prompt style
off-putting, there's a graphical front-end for it xxgdb in the ports
collection.This section is intended to be an introduction to using
gdb and does not cover specialised topics
such as debugging the kernel.Running a program in the debuggerYou'll need to have compiled the program with the
option to get the most out of using
gdb. It will work without, but you'll only
see the name of the function you're in, instead of the source
code. If you see a line like:… (no debugging symbols found) …when gdb starts up, you'll know that
the program wasn't compiled with the
option.At the gdb prompt, type
break main. This will tell the
debugger to skip over the preliminary set-up code in the
program and start at the beginning of your code. Now type
run to start the program—it will
start at the beginning of the set-up code and then get stopped
by the debugger when it calls main().
(If you've ever wondered where main()
gets called from, now you know!).You can now step through the program, a line at a time, by
pressing n. If you get to a function call,
you can step into it by pressing s. Once
you're in a function call, you can return from stepping into a
function call by pressing f. You can also
use up and down to take
a quick look at the caller.Here's a simple example of how to spot a mistake in a
program with gdb. This is our program
(with a deliberate mistake):#include <stdio.h>
int bazz(int anint);
main() {
int i;
printf("This is my program\n");
bazz(i);
return 0;
}
int bazz(int anint) {
printf("You gave me %d\n", anint);
return anint;
}This program sets i to be
5 and passes it to a function
bazz() which prints out the number we
gave it.When we compile and run the program we get&prompt.user; cc -g -o temp temp.c
&prompt.user; ./temp
This is my program
anint = 4231That wasn't what we expected! Time to see what's going
on!&prompt.user; gdb temp
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
(gdb) break main> Skip the set-up code>
Breakpoint 1 at 0x160f: file temp.c, line 9. gdb puts breakpoint at main()>>
(gdb) run> Run as far as main()>>
Starting program: /home/james/tmp/temp Program starts running>
Breakpoint 1, main () at temp.c:9 gdb stops at main()>>
(gdb) n> Go to next line>
This is my program Program prints out>
(gdb) s> step into bazz()>>
bazz (anint=4231) at temp.c:17 gdb displays stack frame>
(gdb)Hang on a minute! How did anint get to be
4231? Didn't we set it to be
5 in main()? Let's
move up to main() and have a look.(gdb) up> Move up call stack>
#1 0x1625 in main () at temp.c:11 gdb displays stack frame>
(gdb) p i> Show us the value of i>>
$1 = 4231 gdb displays 4231>>Oh dear! Looking at the code, we forgot to initialise
i. We meant to put…>
main() {
int i;
i = 5;
printf("This is my program\n");
&hellip>but we left the i=5; line out. As we
didn't initialise i, it had whatever number
happened to be in that area of memory when the program ran,
which in this case happened to be
4231.gdb displays the stack frame every
time we go into or out of a function, even if we're using
up and down to move
around the call stack. This shows the name of the function
and the values of its arguments, which helps us keep track
of where we are and what's going on. (The stack is a
storage area where the program stores information about the
arguments passed to functions and where to go when it
returns from a function call).Examining a core fileA core file is basically a file which contains the
complete state of the process when it crashed. In the
good old days, programmers had to print out hex
listings of core files and sweat over machine code manuals,
but now life is a bit easier. Incidentally, under FreeBSD and
other 4.4BSD systems, a core file is called
progname.core instead of just
core, to make it clearer which program a
core file belongs to.To examine a core file, start up gdb in
the usual way. Instead of typing break or
run, type(gdb) core progname.coreIf you're not in the same directory as the core file,
you'll have to do dir
/path/to/core/file first.You should see something like this:&prompt.user; gdb a.out
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
(gdb) core a.out.core
Core was generated by `a.out'.
Program terminated with signal 11, Segmentation fault.
Cannot access memory at address 0x7020796d.
#0 0x164a in bazz (anint=0x5) at temp.c:17
(gdb)In this case, the program was called
a.out, so the core file is called
a.out.core. We can see that the program
crashed due to trying to access an area in memory that was not
available to it in a function called
bazz.Sometimes it's useful to be able to see how a function was
called, as the problem could have occurred a long way up the
call stack in a complex program. The bt
command causes gdb to print out a
back-trace of the call stack:(gdb) bt
#0 0x164a in bazz (anint=0x5) at temp.c:17
#1 0xefbfd888 in end ()
#2 0x162c in main () at temp.c:11
(gdb)The end() function is called when a
program crashes; in this case, the bazz()
function was called from main().Attaching to a running programOne of the neatest features about gdb
is that it can attach to a program that's already running. Of
course, that assumes you have sufficient permissions to do so.
A common problem is when you are stepping through a program
that forks, and you want to trace the child, but the debugger
will only let you trace the parent.What you do is start up another gdb,
use ps to find the process ID for the
child, and do(gdb) attach pidin gdb, and then debug as usual.That's all very well, you're probably
thinking, but by the time I've done that, the child
process will be over the hill and far away. Fear
not, gentle reader, here's how to do it (courtesy of the
gdb info pages):&hellip
if ((pid = fork()) < 0) /* _Always_ check this */
error();
else if (pid == 0) { /* child */
int PauseMode = 1;
while (PauseMode)
sleep(10); /* Wait until someone attaches to us */
&hellip
} else { /* parent */
&hellipNow all you have to do is attach to the child, set
PauseMode to 0, and wait
for the sleep() call to return!Using Emacs as a Development EnvironmentEmacsUnfortunately, Unix systems don't come with the kind of
everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package
integrated development environments that other systems
have.
Some powerful, free IDEs now exist, such as KDevelop
in the ports collection.
However, it is possible to set up your own environment. It
may not be as pretty, and it may not be quite as integrated,
but you can set it up the way you want it. And it's free.
And you have the source to it.The key to it all is Emacs. Now there are some people who
loathe it, but many who love it. If you're one of the former,
I'm afraid this section will hold little of interest to you.
Also, you'll need a fair amount of memory to run it—I'd
recommend 8MB in text mode and 16MB in X as the bare minimum
to get reasonable performance.Emacs is basically a highly customisable
editor—indeed, it has been customised to the point where
it's more like an operating system than an editor! Many
developers and sysadmins do in fact spend practically all
their time working inside Emacs, leaving it only to log
out.It's impossible even to summarise everything Emacs can do
here, but here are some of the features of interest to
developers:Very powerful editor, allowing search-and-replace on
both strings and regular expressions (patterns), jumping
to start/end of block expression, etc, etc.Pull-down menus and online help.Language-dependent syntax highlighting and
indentation.Completely customisable.You can compile and debug programs within
Emacs.On a compilation error, you can jump to the offending
line of source code.Friendly-ish front-end to the info
program used for reading GNU hypertext documentation,
including the documentation on Emacs itself.Friendly front-end to gdb, allowing
you to look at the source code as you step through your
program.You can read Usenet news and mail while your program
is compiling.And doubtless many more that I've overlooked.Emacs can be installed on FreeBSD using the Emacs
+ URL="../../../../ports/editors.html">the Emacs
port.Once it's installed, start it up and do C-h
t to read an Emacs tutorial—that means
hold down the control key, press
h, let go of the control
key, and then press t. (Alternatively, you
can you use the mouse to select Emacs
Tutorial from the Help
menu).Although Emacs does have menus, it's well worth learning
the key bindings, as it's much quicker when you're editing
something to press a couple of keys than to try and find the
mouse and then click on the right place. And, when you're
talking to seasoned Emacs users, you'll find they often
casually throw around expressions like M-x
replace-s RET foo RET bar RET so it's
useful to know what they mean. And in any case, Emacs has far
too many useful functions for them to all fit on the menu
bars.Fortunately, it's quite easy to pick up the key-bindings,
as they're displayed next to the menu item. My advice is to
use the menu item for, say, opening a file until you
understand how it works and feel confident with it, then try
doing C-x C-f. When you're happy with that, move on to
another menu command.If you can't remember what a particular combination of
keys does, select Describe Key from
the Help menu and type it in—Emacs
will tell you what it does. You can also use the
Command Apropos menu item to find
out all the commands which contain a particular word in them,
with the key binding next to it.By the way, the expression above means hold down the
Meta key, press x, release
the Meta key, type
replace-s (short for
replace-string—another feature of
Emacs is that you can abbreviate commands), press the
return key, type foo
(the string you want replaced), press the
return key, type bar (the string you want to
replace foo with) and press
return again. Emacs will then do the
search-and-replace operation you've just requested.If you're wondering what on earth the
Meta key is, it's a special key that many
Unix workstations have. Unfortunately, PC's don't have one,
so it's usually the alt key (or if you're
unlucky, the escape key).Oh, and to get out of Emacs, do C-x C-c
(that means hold down the control key, press
x, press c and release the
control key). If you have any unsaved files
open, Emacs will ask you if you want to save them. (Ignore
the bit in the documentation where it says
C-z is the usual way to leave
Emacs—that leaves Emacs hanging around in the
background, and is only really useful if you're on a system
which doesn't have virtual terminals).Configuring EmacsEmacs does many wonderful things; some of them are built
in, some of them need to be configured.Instead of using a proprietary macro language for
configuration, Emacs uses a version of Lisp specially adapted
for editors, known as Emacs Lisp. This can be quite useful if
you want to go on and learn something like Common Lisp, as
it's considerably smaller than Common Lisp (although still
quite big!).The best way to learn Emacs Lisp is to download the Emacs
+ URL="ftp://prep.ai.mit.edu/pub/gnu/elisp-manual-19-2.4.tar.gz">Emacs
TutorialHowever, there's no need to actually know any Lisp to get
started with configuring Emacs, as I've included a sample
.emacs file, which should be enough to
get you started. Just copy it into your home directory and
restart Emacs if it's already running; it will read the
commands from the file and (hopefully) give you a useful basic
setup.A sample .emacs fileUnfortunately, there's far too much here to explain it in
detail; however there are one or two points worth
mentioning.Everything beginning with a ; is a comment
and is ignored by Emacs.In the first line, the
-*- Emacs-Lisp -*- is so that
we can edit the .emacs file itself
within Emacs and get all the fancy features for editing
Emacs Lisp. Emacs usually tries to guess this based on
the filename, and may not get it right for
.emacs.The tab key is bound to an
indentation function in some modes, so when you press the
tab key, it will indent the current line of code. If you
want to put a tab character in whatever
you're writing, hold the control key down
while you're pressing the tab key.This file supports syntax highlighting for C, C++,
Perl, Lisp and Scheme, by guessing the language from the
filename.Emacs already has a pre-defined function called
next-error. In a compilation output
window, this allows you to move from one compilation error
to the next by doing M-n; we define a
complementary function,
previous-error, that allows you to go
to a previous error by doing M-p. The
nicest feature of all is that C-c C-c
will open up the source file in which the error occurred
and jump to the appropriate line.We enable Emacs's ability to act as a server, so that
if you're doing something outside Emacs and you want to
edit a file, you can just type in&prompt.user; emacsclient filenameand then you can edit the file in your
Emacs!
Many Emacs users set their EDITOR
environment to
emacsclient so this happens every
time they need to edit a file.A sample .emacs file;; -*-Emacs-Lisp-*-
;; This file is designed to be re-evaled; use the variable first-time
;; to avoid any problems with this.
(defvar first-time t
"Flag signifying this is the first time that .emacs has been evaled")
;; Meta
(global-set-key "\M- " 'set-mark-command)
(global-set-key "\M-\C-h" 'backward-kill-word)
(global-set-key "\M-\C-r" 'query-replace)
(global-set-key "\M-r" 'replace-string)
(global-set-key "\M-g" 'goto-line)
(global-set-key "\M-h" 'help-command)
;; Function keys
(global-set-key [f1] 'manual-entry)
(global-set-key [f2] 'info)
(global-set-key [f3] 'repeat-complex-command)
(global-set-key [f4] 'advertised-undo)
(global-set-key [f5] 'eval-current-buffer)
(global-set-key [f6] 'buffer-menu)
(global-set-key [f7] 'other-window)
(global-set-key [f8] 'find-file)
(global-set-key [f9] 'save-buffer)
(global-set-key [f10] 'next-error)
(global-set-key [f11] 'compile)
(global-set-key [f12] 'grep)
(global-set-key [C-f1] 'compile)
(global-set-key [C-f2] 'grep)
(global-set-key [C-f3] 'next-error)
(global-set-key [C-f4] 'previous-error)
(global-set-key [C-f5] 'display-faces)
(global-set-key [C-f8] 'dired)
(global-set-key [C-f10] 'kill-compilation)
;; Keypad bindings
(global-set-key [up] "\C-p")
(global-set-key [down] "\C-n")
(global-set-key [left] "\C-b")
(global-set-key [right] "\C-f")
(global-set-key [home] "\C-a")
(global-set-key [end] "\C-e")
(global-set-key [prior] "\M-v")
(global-set-key [next] "\C-v")
(global-set-key [C-up] "\M-\C-b")
(global-set-key [C-down] "\M-\C-f")
(global-set-key [C-left] "\M-b")
(global-set-key [C-right] "\M-f")
(global-set-key [C-home] "\M-<")
(global-set-key [C-end] "\M->")
(global-set-key [C-prior] "\M-<")
(global-set-key [C-next] "\M->")
;; Mouse
(global-set-key [mouse-3] 'imenu)
;; Misc
(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab.
(setq backup-by-copying-when-mismatch t)
;; Treat 'y' or <CR> as yes, 'n' as no.
(fset 'yes-or-no-p 'y-or-n-p)
(define-key query-replace-map [return] 'act)
(define-key query-replace-map [?\C-m] 'act)
;; Load packages
(require 'desktop)
(require 'tar-mode)
;; Pretty diff mode
(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t)
(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t)
(autoload 'ediff-files-remote "ediff"
"Intelligent Emacs interface to diff")
(if first-time
(setq auto-mode-alist
(append '(("\\.cpp$" . c++-mode)
("\\.hpp$" . c++-mode)
("\\.lsp$" . lisp-mode)
("\\.scm$" . scheme-mode)
("\\.pl$" . perl-mode)
) auto-mode-alist)))
;; Auto font lock mode
(defvar font-lock-auto-mode-list
(list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode)
"List of modes to always start in font-lock-mode")
(defvar font-lock-mode-keyword-alist
'((c++-c-mode . c-font-lock-keywords)
(perl-mode . perl-font-lock-keywords))
"Associations between modes and keywords")
(defun font-lock-auto-mode-select ()
"Automatically select font-lock-mode if the current major mode is
in font-lock-auto-mode-list"
(if (memq major-mode font-lock-auto-mode-list)
(progn
(font-lock-mode t))
)
)
(global-set-key [M-f1] 'font-lock-fontify-buffer)
;; New dabbrev stuff
;(require 'new-dabbrev)
(setq dabbrev-always-check-other-buffers t)
(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_")
(add-hook 'emacs-lisp-mode-hook
'(lambda ()
(set (make-local-variable 'dabbrev-case-fold-search) nil)
(set (make-local-variable 'dabbrev-case-replace) nil)))
(add-hook 'c-mode-hook
'(lambda ()
(set (make-local-variable 'dabbrev-case-fold-search) nil)
(set (make-local-variable 'dabbrev-case-replace) nil)))
(add-hook 'text-mode-hook
'(lambda ()
(set (make-local-variable 'dabbrev-case-fold-search) t)
(set (make-local-variable 'dabbrev-case-replace) t)))
;; C++ and C mode...
(defun my-c++-mode-hook ()
(setq tab-width 4)
(define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
(define-key c++-mode-map "\C-ce" 'c-comment-edit)
(setq c++-auto-hungry-initial-state 'none)
(setq c++-delete-function 'backward-delete-char)
(setq c++-tab-always-indent t)
(setq c-indent-level 4)
(setq c-continued-statement-offset 4)
(setq c++-empty-arglist-indent 4))
(defun my-c-mode-hook ()
(setq tab-width 4)
(define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent)
(define-key c-mode-map "\C-ce" 'c-comment-edit)
(setq c-auto-hungry-initial-state 'none)
(setq c-delete-function 'backward-delete-char)
(setq c-tab-always-indent t)
;; BSD-ish indentation style
(setq c-indent-level 4)
(setq c-continued-statement-offset 4)
(setq c-brace-offset -4)
(setq c-argdecl-indent 0)
(setq c-label-offset -4))
;; Perl mode
(defun my-perl-mode-hook ()
(setq tab-width 4)
(define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
(setq perl-indent-level 4)
(setq perl-continued-statement-offset 4))
;; Scheme mode...
(defun my-scheme-mode-hook ()
(define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent))
;; Emacs-Lisp mode...
(defun my-lisp-mode-hook ()
(define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent)
(define-key lisp-mode-map "\C-i" 'lisp-indent-line)
(define-key lisp-mode-map "\C-j" 'eval-print-last-sexp))
;; Add all of the hooks...
(add-hook 'c++-mode-hook 'my-c++-mode-hook)
(add-hook 'c-mode-hook 'my-c-mode-hook)
(add-hook 'scheme-mode-hook 'my-scheme-mode-hook)
(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook)
(add-hook 'lisp-mode-hook 'my-lisp-mode-hook)
(add-hook 'perl-mode-hook 'my-perl-mode-hook)
;; Complement to next-error
(defun previous-error (n)
"Visit previous compilation error message and corresponding source code."
(interactive "p")
(next-error (- n)))
;; Misc...
(transient-mark-mode 1)
(setq mark-even-if-inactive t)
(setq visible-bell nil)
(setq next-line-add-newlines nil)
(setq compile-command "make")
(setq suggest-key-bindings nil)
(put 'eval-expression 'disabled nil)
(put 'narrow-to-region 'disabled nil)
(put 'set-goal-column 'disabled nil)
;; Elisp archive searching
(autoload 'format-lisp-code-directory "lispdir" nil t)
(autoload 'lisp-dir-apropos "lispdir" nil t)
(autoload 'lisp-dir-retrieve "lispdir" nil t)
(autoload 'lisp-dir-verify "lispdir" nil t)
;; Font lock mode
(defun my-make-face (face colour &optional bold)
"Create a face from a colour and optionally make it bold"
(make-face face)
(copy-face 'default face)
(set-face-foreground face colour)
(if bold (make-face-bold face))
)
(if (eq window-system 'x)
(progn
(my-make-face 'blue "blue")
(my-make-face 'red "red")
(my-make-face 'green "dark green")
(setq font-lock-comment-face 'blue)
(setq font-lock-string-face 'bold)
(setq font-lock-type-face 'bold)
(setq font-lock-keyword-face 'bold)
(setq font-lock-function-name-face 'red)
(setq font-lock-doc-string-face 'green)
(add-hook 'find-file-hooks 'font-lock-auto-mode-select)
(setq baud-rate 1000000)
(global-set-key "\C-cmm" 'menu-bar-mode)
(global-set-key "\C-cms" 'scroll-bar-mode)
(global-set-key [backspace] 'backward-delete-char)
; (global-set-key [delete] 'delete-char)
(standard-display-european t)
(load-library "iso-transl")))
;; X11 or PC using direct screen writes
(if window-system
(progn
;; (global-set-key [M-f1] 'hilit-repaint-command)
;; (global-set-key [M-f2] [?\C-u M-f1])
(setq hilit-mode-enable-list
'(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode
scheme-mode)
hilit-auto-highlight nil
hilit-auto-rehighlight 'visible
hilit-inhibit-hooks nil
hilit-inhibit-rebinding t)
(require 'hilit19)
(require 'paren))
(setq baud-rate 2400) ; For slow serial connections
)
;; TTY type terminal
(if (and (not window-system)
(not (equal system-type 'ms-dos)))
(progn
(if first-time
(progn
(keyboard-translate ?\C-h ?\C-?)
(keyboard-translate ?\C-? ?\C-h)))))
;; Under UNIX
(if (not (equal system-type 'ms-dos))
(progn
(if first-time
(server-start))))
;; Add any face changes here
(add-hook 'term-setup-hook 'my-term-setup-hook)
(defun my-term-setup-hook ()
(if (eq window-system 'pc)
(progn
;; (set-face-background 'default "red")
)))
;; Restore the "desktop" - do this as late as possible
(if first-time
(progn
(desktop-load-default)
(desktop-read)))
;; Indicate that this file has been read at least once
(setq first-time nil)
;; No need to debug anything now
(setq debug-on-error nil)
;; All done
(message "All done, %s%s" (user-login-name) ".")
Extending the Range of Languages Emacs UnderstandsNow, this is all very well if you only want to program in
the languages already catered for in the
.emacs file (C, C++, Perl, Lisp and
Scheme), but what happens if a new language called
whizbang comes out, full of exciting
features?The first thing to do is find out if whizbang comes with
any files that tell Emacs about the language. These usually
end in .el, short for Emacs
Lisp. For example, if whizbang is a FreeBSD port, we
can locate these files by doing&prompt.user; find /usr/ports/lang/whizbang -name "*.el" -printand install them by copying them into the Emacs site Lisp
directory. On FreeBSD 2.1.0-RELEASE, this is
/usr/local/share/emacs/site-lisp.So for example, if the output from the find command
was/usr/ports/lang/whizbang/work/misc/whizbang.elwe would do&prompt.root; cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lispNext, we need to decide what extension whizbang source
files have. Let's say for the sake of argument that they all
end in .wiz. We need to add an entry to
our .emacs file to make sure Emacs will
be able to use the information in
whizbang.el.Find the auto-mode-alist entry in
.emacs and add a line for whizbang, such
as:…>
("\\.lsp$" . lisp-mode)
("\\.wiz$" . whizbang-mode)
("\\.scm$" . scheme-mode)
…>This means that Emacs will automatically go into
whizbang-mode when you edit a file ending
in .wiz.Just below this, you'll find the
font-lock-auto-mode-list entry. Add
whizbang-mode to it like so:;; Auto font lock mode
(defvar font-lock-auto-mode-list
(list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode)
"List of modes to always start in font-lock-mode")This means that Emacs will always enable
font-lock-mode (ie syntax highlighting)
when editing a .wiz file.And that's all that's needed. If there's anything else
you want done automatically when you open up a
.wiz file, you can add a
whizbang-mode hook (see
my-scheme-mode-hook for a simple example
that adds auto-indent).Further ReadingBrian Harvey and Matthew Wright
Simply Scheme
MIT 1994.
ISBN 0-262-08226-8Randall Schwartz
Learning Perl
O'Reilly 1993
ISBN 1-56592-042-2Patrick Henry Winston and Berthold Klaus Paul Horn
Lisp (3rd Edition)
Addison-Wesley 1989
ISBN 0-201-08319-1Brian W. Kernighan and Rob Pike
The Unix Programming Environment
Prentice-Hall 1984
ISBN 0-13-937681-XBrian W. Kernighan and Dennis M. Ritchie
The C Programming Language (2nd Edition)
Prentice-Hall 1988
ISBN 0-13-110362-8Bjarne Stroustrup
The C++ Programming Language
Addison-Wesley 1991
ISBN 0-201-53992-6W. Richard Stevens
Advanced Programming in the Unix Environment
Addison-Wesley 1992
ISBN 0-201-56317-7W. Richard Stevens
Unix Network Programming
Prentice-Hall 1990
ISBN 0-13-949876-1
diff --git a/en_US.ISO8859-1/books/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml
index 814df87057..5bb0077bb6 100644
--- a/en_US.ISO8859-1/books/faq/book.sgml
+++ b/en_US.ISO8859-1/books/faq/book.sgml
@@ -1,12517 +1,12517 @@
%man;
%freebsd;
%authors;
%bookinfo;
%mailing-lists;
]>
Frequently Asked Questions for FreeBSD 2.X, 3.X and 4.XThe FreeBSD Documentation Project$FreeBSD$1995199619971998199920002001The FreeBSD Documentation Project
&bookinfo.legalnotice;
This is the FAQ for FreeBSD versions 2.X, 3.X, and 4.X.
All entries are assumed to be relevant to FreeBSD 2.0.5 and later,
unless otherwise noted. Any entries with a <XXX> are under
construction. If you are interested in helping with this project,
send email to the &a.doc;. The latest version of this
document is always available from the FreeBSD World Wide Web
+ URL="../../../../index.html">FreeBSD World Wide Web
server. It may also be downloaded as one large HTML file with HTTP or as plain text,
postscript, PDF, etc. from the FreeBSD FTP
server. You may also want to Search the
+ URL="../../../../search/index.html">Search the
FAQ.IntroductionWelcome to the FreeBSD 2.X-4.X FAQ!As is usual with Usenet FAQs, this document aims to cover the
most frequently asked questions concerning the FreeBSD operating
system (and of course answer them!). Although originally intended
to reduce bandwidth and avoid the same old questions being asked
over and over again, FAQs have become recognized as valuable
information resources.Every effort has been made to make this FAQ as informative as
possible; if you have any suggestions as to how it may be improved,
please feel free to mail them to the &a.faq;.What is FreeBSD?Briefly, FreeBSD is a UN*X-like operating system for the
i386 and Alpha/AXP platforms based on U.C. Berkeley's
4.4BSD-Lite release, with some 4.4BSD-Lite2 enhancements.
It is also based indirectly on William Jolitz's port of U.C.
Berkeley's Net/2 to the i386, known as 386BSD, though very
little of the 386BSD code remains. A fuller description of
what FreeBSD is and how it can work for you may be found on
- the FreeBSD home
+ the FreeBSD home
page.FreeBSD is used by companies, Internet Service Providers,
researchers, computer professionals, students and home users
all over the world in their work, education and recreation.
See some of them in the FreeBSD
+ URL="../../../../gallery/index.html">FreeBSD
Gallery.For more detailed information on FreeBSD, please see the
FreeBSD
Handbook.What are the goals of FreeBSD?The goals of the FreeBSD Project are to provide software
that may be used for any purpose and without strings attached.
Many of us have a significant investment in the code (and
project) and would certainly not mind a little financial
compensation now and then, but we are definitely not prepared
to insist on it. We believe that our first and foremost
mission is to provide code to any and all
comers, and for whatever purpose, so that the code gets the
widest possible use and provides the widest possible benefit.
This is, we believe, one of the most fundamental goals of Free
Software and one that we enthusiastically support.That code in our source tree which falls under the GNU General Public
+ url="../../../../copyright/COPYING">GNU General Public
License (GPL) or GNU Library
+ url="../../../../copyright/COPYING.LIB">GNU Library
General Public License (LGPL) comes with slightly more
strings attached, though at least on the side of enforced access
rather than the usual opposite. Due to the additional complexities
that can evolve in the commercial use of GPL software, we do,
however, endeavor to replace such software with submissions under
the more relaxed
+ url="../../../../copyright/freebsd-license.html">
FreeBSD copyright whenever possible.Why is it called FreeBSD?It may be used free of charge, even by commercial
users.Full source for the operating system is freely
available, and the minimum possible restrictions have
been placed upon its use, distribution and incorporation
into other work (commercial or non-commercial).Anyone who has an improvement and/or bug fix is free
to submit their code and have it added to the source tree
(subject to one or two obvious provisions).For those of our readers whose first language is not
English, it may be worth pointing out that the word
free is being used in two ways here, one meaning
at no cost, the other meaning you can do
whatever you like. Apart from one or two things you
cannot do with the FreeBSD code, for
example pretending you wrote it, you really can do whatever you
like with it.What is the latest version of FreeBSD?Version &rel.current;
is the latest STABLE version; it was
released in &rel.current.date;. This is also the latest
RELEASE version.Briefly explained, -STABLE is aimed
at the ISP or other corporate user who wants stability and a
low change count over the wizzy new features of the latest
-CURRENT snapshot. Releases can come
from either branch, but you should only use
-CURRENT if you are sure that you are
prepared for its increased volatility (relative to
-STABLE, that is).Releases are only made every
few months. While many people stay more up-to-date with
the FreeBSD sources (see the questions on FreeBSD-CURRENT and FreeBSD-STABLE) than that, doing so
is more of a commitment, as the sources are a moving
target.What is FreeBSD-CURRENT?FreeBSD-CURRENT
is the development version of the operating system, which will
in due course become 5.0-RELEASE. As such, it is really only
of interest to developers working on the system and die-hard
hobbyists. See the relevant
section in the handbook for details on
running -CURRENT.If you are not familiar with the operating system or are
not capable of identifying the difference between a real
problem and a temporary problem, you should not use
FreeBSD-CURRENT. This branch sometimes evolves quite quickly
and can be un-buildable for a number of days at a time.
People that use FreeBSD-CURRENT are expected to be able to
analyze any problems and only report them if they are deemed
to be mistakes rather than glitches. Questions
such as make world produces some error about
groups on the -CURRENT mailing list are sometimes
treated with contempt.Every day, snapshot
+ URL="../../../../releases/snapshots.html">snapshot
releases are made based on the current state of the
-CURRENT and -STABLE branches. Nowadays, distributions of the
occasional snapshot are now being made available. The goals
behind each snapshot release are:To test the latest version of the installation
software.To give people who would like to run -CURRENT or
-STABLE but who do not have the time and/or bandwidth to
follow it on a day-to-day basis an easy way of
bootstrapping it onto their systems.To preserve a fixed reference point for the code in
question, just in case we break something really badly
later. (Although CVS normally prevents anything horrible
like this happening :)To ensure that any new features in need of testing
have the greatest possible number of potential
testers.No claims are made that any -CURRENT snapshot can be
considered production quality for any purpose.
If you want to run a stable and fully tested system, you will
have to stick to full releases, or use the -STABLE
snaphosts.Snapshot releases are directly available from
ftp://current.FreeBSD.org/pub/FreeBSD/ for 5.0-CURRENT
and
releng4.FreeBSD.org for 4-STABLE snapshots.
3-STABLE snapshots are not being produced at the time of
this writing (May 2000).Snapshots are generated, on the average, once a day for
all actively developed branches.What is the FreeBSD-STABLE concept?Back when FreeBSD 2.0.5 was released, we decided to
branch FreeBSD development into two parts. One branch was
- named -STABLE,
+ named -STABLE,
with the intention that only well-tested bug fixes and small
incremental enhancements would be made to it (for Internet
Service Providers and other commercial enterprises for whom
sudden shifts or experimental features are quite
undesirable). The other branch was -CURRENT,
which essentially has been one unbroken line leading towards
5.0-RELEASE (and beyond) since 2.0 was released. If a little
ASCII art would help, this is how it looks: 2.0
|
|
| [2.1-STABLE]
*BRANCH* 2.0.5 -> 2.1 -> 2.1.5 -> 2.1.6 -> 2.1.7.1 [2.1-STABLE ends]
| (Mar 1997)
|
|
| [2.2-STABLE]
*BRANCH* 2.2.1 -> 2.2.2-RELEASE -> 2.2.5 -> 2.2.6 -> 2.2.7 -> 2.2.8 [end]
| (Mar 1997) (Oct 97) (Apr 98) (Jul 98) (Dec 98)
|
|
3.0-SNAPs (started Q1 1997)
|
|
3.0-RELEASE (Oct 1998)
|
| [3.0-STABLE]
*BRANCH* 3.1-RELEASE (Feb 1999) -> 3.2 -> 3.3 -> 3.4 -> 3.5 -> 3.5.1
| (May 1999) (Sep 1999) (Dec 1999) (June 2000) (July 2000)
|
| [4.0-STABLE]
*BRANCH* 4.0 (Mar 2000) -> 4.1 -> 4.1.1 -> 4.2 -> 4.3 -> 4.4 -> ... future 4.x releases ...
|
| (July 2000) (Sep 2000) (Nov 2000)
\|/
+
[5.0-CURRENT continues]The 2.2-STABLE branch was retired with the release of 2.2.8.
The 3-STABLE branch has ended with the release of 3.5.1, the
final 3.X release. The only changes made to either of these
branches will be, for the most part, security-related bug
fixes.4-STABLE is the actively developed -STABLE branch. The
latest release on the 4-STABLE is &rel.current;-RELEASE, which was released
in &rel.current.date;.The 5-CURRENT branch is slowly progressing toward 5.0-RELEASE
and beyond. See What is
FreeBSD-CURRENT? for more information on this branch.When are FreeBSD releases made?As a general principle, the FreeBSD core team only release
a new version of FreeBSD when they believe that there are
sufficient new features and/or bug fixes to justify one, and
are satisfied that the changes made have settled down
sufficiently to avoid compromising the stability of the
release. Many users regard this caution as one of the best
things about FreeBSD, although it can be a little frustrating
when waiting for all the latest goodies to become
available...Releases are made about every 4 months on average.For people needing (or wanting) a little more excitement,
binary snapshots are made every day... see above.Who is responsible for FreeBSD?The key decisions concerning the FreeBSD project, such as
the overall direction of the project and who is allowed to add
code to the source tree, are made by a core team of
+ URL="../../articles/contributors/staff-core.html">core team of
9 people. There is a much larger team of more than 200 committers who
+ URL="../../articles/contributors/staff-committers.html">committers who
are authorized to make changes directly to the FreeBSD source
tree.However, most non-trivial changes are discussed in advance
in the mailing lists, and there
are no restrictions on who may take part in the
discussion.Where can I get FreeBSD?Every significant release of FreeBSD is available via
anonymous FTP from the
FreeBSD FTP site:For the current 3.X-STABLE release, 3.5.1-RELEASE, see
the 3.5.1-RELEASE directory.The current 4-STABLE release, &rel.current;-RELEASE can be
found in the &rel.current;-RELEASE directory.4.X
snapshots are usually made once a day.
5.0 Snapshot releases are made once a day for the
-CURRENT branch, these being
of service purely to bleeding-edge testers and
developers.Information about obtaining FreeBSD on CD, DVD, and other
media can be found in the
Handbook.Where do I find info on the FreeBSD mailing lists?You can find full information in the Handbook
entry on mailing-lists.Where do I find the FreeBSD Y2K info?You can find full information in the FreeBSD Y2K
+ URL="../../../../y2kbug.html">FreeBSD Y2K
page.What FreeBSD news groups are available?You can find full information in the Handbook entry on
newsgroups.Are there FreeBSD IRC (Internet Relay Chat)
channels?Yes, most major IRC networks host a FreeBSD chat
channel:Channel #FreeBSD on
EFNet
is a FreeBSD forum, but do not go there for tech
support or to try and get folks there to help you avoid
the pain of reading man pages or doing your own research.
It is a chat channel, first and foremost, and topics there
are just as likely to involve sex, sports or nuclear
weapons as they are FreeBSD. You Have Been Warned!
Available at server irc.chat.org.Channel #FreeBSDhelp on
EFNet
is a channel dedicated to helping FreeBSD users. They
are much more sympathetic to questions then
#FreeBSD is.Channel #FreeBSD on
DALNET
is available at irc.dal.net in the
US and irc.eu.dal.net in Europe.Channel #FreeBSD on
UNDERNET
is available at us.undernet.org
in the US and eu.undernet.org in Europe.
Since it is a help channel, be prepared to read the
documents you are referred to.Channel #FreeBSD on HybNet. This channel
is a help channel. A list of servers
can be found on the HybNet web site.Each of these channels are distinct and are not connected
to each other. Their chat styles also differ, so you may need
to try each to find one suited to your chat style. As with
all types of IRC traffic, if you are easily offended or cannot
deal with lots of young people (and more than a few older
ones) doing the verbal equivalent of jello wrestling, do not
even bother with it.How do I access the Problem Report database?The Problem Report database of all user change requests
may be queried (or submitted to) by using our web-based PR
submission
+ URL="../../../../send-pr.html">submission
and
query
interfaces. The &man.send-pr.1; command can
also be used to submit problem reports and change requests via
electronic mail.Is the documentation available in other formats, such as plain
text (ASCII), or Postscript?Yes. The documentation is available in a number of different
formats and compression schemes on the FreeBSD FTP site, in the
/pub/FreeBSD/doc/ directory.The documentation is categorised in a number of different
ways. These include:The document's name, such as faq, or
handbook.The document's language and encoding. These are based on
the locale names you will find under
/usr/share/locale on your FreeBSD
system. The current languages and encodings that we have for
documentation are as follows:NameMeaningen_US.ISO8859-1US Englishde_DE.ISO8859-1Germanes_ES.ISO8859-1Spanishfr_FR.ISO8859-1Frenchja_JP.eucJPJapanese (EUC encoding)ru_RU.KOI8-RRussian (KOI8-R encoding)zh_TW.Big5Chinese (Big5 encoding)Some documents may not be available in all
languages.The document's format. We produce the documentation in a
number of different output formats to try and make it as
flexible as possible. The current formats are;FormatMeaninghtml-splitA collection of small, linked, HTML
files.htmlOne large HTML file containing the entire
documentpdbPalm Pilot database format, for use with the
iSilo
reader.pdfAdobe's Portable Document FormatpsPostscriptrtfMicrosoft's Rich Text FormatPage numbers are not automatically updated
when loading this format in to Word. Press
CTRLA,
CTRLEND,
F9 after loading the document, to
update the page numbers.txtPlain textThe compression and packaging scheme. There are three of
these currently in use.Where the format is html-split, the
files are bundled up using &man.tar.1;. The resulting
.tar file is then compressed using
the compression schemes detailed in the next point.All the other formats generate one file, called
book.format
(i.e., book.pdb,
book.html, and so on).These files are then compressed using three
compression schemes.SchemeDescriptionzipThe Zip format. If you want to uncompress
this on FreeBSD you will need to install the
archivers/unzip port
first.gzThe GNU Zip format. Use &man.gunzip.1; to
uncompress these files, which is part of
FreeBSD.bz2The BZip2 format. Less widespread than the
others, but generally gives smaller files.
Install the archivers/bzip2
port to uncompress these files.So the Postscript version of the Handbook, compressed
using BZip2 will be stored in a file called
book.ps.bz2 in the
handbook/ directory.The formatted documentation is also available as a
FreeBSD package, of which more later.After choosing the format and compression mechanism that you
want to download, you must then decide whether or not you want to
download the document as a FreeBSD
package.The advantage of downloading and installing the package is
that the documentation can then be managed using the normal
FreeBSD package management comments, such as &man.pkg.add.1; and
&man.pkg.delete.1;.If you decide to download and install the package then you
must know the filename to download. The documentation-as-packages
files are stored in a directory called
packages. Each package file looks like
document-name.lang.encoding.format.tgz.For example, the FAQ, in English, formatted as PDF, is in the
package called
faq.en_US.ISO8859-1.pdf.tgz.Knowing this, you can use the following command to install the
English PDF FAQ package.&prompt.root; pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO8859-1.pdf.tgzHaving done that, you can use &man.pkg.info.1; to determine
where the file has been installed.&prompt.root; pkg_info -f faq.en_US.ISO8859-1.pdf
Information for faq.en_US.ISO8859-1.pdf:
Packing list:
Package name: faq.en_US.ISO8859-1.pdf
CWD to /usr/share/doc/en_US.ISO8859-1/books/faq
File: book.pdf
CWD to .
File: +COMMENT (ignored)
File: +DESC (ignored)As you can see, book.pdf will have been
installed in to
/usr/share/doc/en_US.ISO8859-1/books/faq.
If you do not want to use the packages then you will have to
download the compressed files yourself, uncompress them, and then
copy the appropriate documents in to place.For example, the split HTML version of the FAQ, compressed
using &man.gzip.1;, can be found in the
- en_US.ISO8859-1/books/faq/book.html-split.tar.gz
+ doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz
file. To download and uncompress that file you would have to do
this.
- &prompt.root; fetch ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz
+ &prompt.root; fetch ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz
&prompt.root; gzip -d book.html-split.tar.gz
&prompt.root; tar xvf book.html-split.tarYou will be left with a collection of
.html files. The main one is called
index.html, which will contain the table of
contents, introductory material, and links to the other parts of
the document. You can then copy or move these to their final
location as necessary.How do I become a FreeBSD Web mirror?Certainly! There are multiple ways to mirror the Web
pages.Using CVSup:
You can retrieve the formatted files
using CVSup, and connecting to
a CVSup server.To retrieve the webpages, please look at the example
supfile, which can be found in
/usr/share/examples/cvsup/www-supfile.
Using FTP mirror: You can download the FTP server's
copy of the web site sources using your favorite ftp mirror
tool. Keep in mind that you have to build these sources before
publishing them. Simply start at
ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/www.What other sources of information are there?The following newsgroups contain pertinent discussion for
FreeBSD users:comp.unix.bsd.freebsd.announce
(moderated)comp.unix.bsd.freebsd.misccomp.unix.bsd.miscWeb resources:The FreeBSD Home Page.
+ URL="../../../../index.html">FreeBSD Home Page.
If you have a laptop, be sure and see
Tatsumi
Hosokawa's Mobile Computing page in Japan.For information on SMP (Symmetric
MultiProcessing), please see the SMP support page.For information on FreeBSD
multimedia applications, please see the multimedia
page. If you are interested specifically in the Bt848
video capture chip, then follow that link.The FreeBSD handbook also has a fairly complete bibliography
section which is worth reading if you are looking for actual
books to buy.NikClayton
- nik@freebsd.org
+ nik@FreeBSD.orgInstallationWhich file do I download to get FreeBSD?Prior to release 3.1, you only needed one floppy image to
install FreeBSD, namely floppies/boot.flp.
However, since release 3.1 the Project has added base support
for a wide variety of hardware which needed more space, and
thus for 3.x and 4.x we now use two floppy images, namely
floppies/kernel.flp and
floppies/mfsroot.flp. These images need to
be copied onto floppies by tools like
fdimage or &man.dd.1;.If you need to download the distributions yourself (for a
DOS filesystem install, for instance), below are some
recommendations for distributions to grab:bin/manpages/compat*/doc/src/ssys.*Full instructions on this procedure and a little bit more
about installation issues in general can be found in the
Handbook entry on
installing FreeBSD.What do I do if the floppy images does not fit on a single
floppy?A 3.5 inch (1.44MB) floppy can accomodate 1474560 bytes
of data. The boot image is exactly 1474560 bytes in size.Common mistakes when preparing the boot floppy are:Not downloading the floppy image in
binary mode when using
FTP.Some FTP clients default their transfer mode to
ascii and attempt to change any
end-of-line characters received to match the conventions
used by the client's system. This will almost invariably
corrupt the boot image. Check the size of the downloaded
boot image: if it is not exactly that
on the server, then the download process is suspect.To workaround: type binary at the
FTP command prompt after getting connected to the server
and before starting the download of the image.Using the DOS copy command (or
equivalent GUI tool) to transfer the boot image to
floppy.Programs like copy will not work as
the boot image has been created to be booted into directly.
The image has the complete content of the floppy, track for
track, and is not meant to be placed on the floppy as a
regular file. You have to transfer it to the floppy
raw, using the low-level tools (e.g.
fdimage or rawrite)
described in the installation guide to
FreeBSD.Where are the instructions for installing FreeBSD?Installation instructions can be found in the
Handbook entry on installing FreeBSD.What do I need in order to run FreeBSD?You will need a 386 or better PC, with 5 MB or more of RAM
and at least 60 MB of hard disk space. It can run with a low
end MDA graphics card but to run X11R6, a VGA or better video
card is needed.See also the section on
I have only 4 MB of RAM. Can I install FreeBSD?FreeBSD 2.1.7 was the last version of FreeBSD that could
be installed on a 4MB system. Newer versions of FreeBSD, like
2.2, need at least 5MB to install on a new system.All versions of FreeBSD, including 3.0, will
run in 4MB of RAM, they just cannot run the
installation program in 4MB. You can add extra memory for the
install process, if you like, and then after the system is up
and running, go back to 4MB. Or you could always just swap your
disk into a system which has >4MB, install onto it and then
swap it back.There are also situations in which FreeBSD 2.1.7 will not
install in 4 MB. To be exact: it does not install with 640 kB
base + 3 MB extended memory. If your motherboard can remap some
of the lost memory out of the 640kB to 1MB
region, then you may still be able to get FreeBSD 2.1.7
up.Try to go into your BIOS setup and look for a
remap option. Enable it. You may also have to
disable ROM shadowing.It may be easier to get 4 more MB just for the install.
Build a custom kernel with only the options you need and then
get the 4MB out again.You may also install 2.0.5 and then upgrade your system to
2.1.7 with the upgrade option of the 2.1.7
installation program.After the installation, if you build a custom kernel, it
will run in 4 MB. Someone has even succeeded in booting with 2
MB (the system was almost unusable though :-))How can I make my own custom install floppy?Currently there is no way to just
make a custom install floppy. You have to cut a whole new
release, which will include your install floppy.To make a custom release, follow the instructions
here.Can I have more than one operating system on my PC?Have a look at
-
+
The multi-OS page.Can Windows 95/98 co-exist with FreeBSD?Install Windows 95/98 first, after that FreeBSD.
FreeBSD's boot manager will then manage to boot Win95/98 and
FreeBSD. If you install Windows 95/98 second, it will boorishly
overwrite your boot manager without even asking. If that
happens, see the next section.Windows 95/98 killed my boot manager!
How do I get it back?You can reinstall the boot manager FreeBSD comes with in
one of three ways:Running DOS, go into the tools/ directory of your
FreeBSD distribution and look for
bootinst.exe. You run it like
so:...\TOOLS>bootinst.exe boot.binand the boot manager will be reinstalled.Boot the FreeBSD boot floppy again and go to the
Custom installation menu item. Choose Partition. Select the
drive which used to contain your boot manager (likely the
first one) and when you come to the partition editor for
it, as the very first thing (e.g. do not make any changes)
select (W)rite. This will ask for confirmation, say yes,
and when you get the Boot Manager selection prompt, be
sure to select Boot Manager. This will
re-write the boot manager to disk. Now quit out of the
installation menu and reboot off the hard disk as
normal.Boot the FreeBSD boot floppy (or CDROM) and choose the
Fixit menu item. Select either the Fixit
floppy or CDROM #2 (the live file system
option) as appropriate and enter the fixit shell. Then
execute the following command:Fixit#fdisk -B -b /boot/boot0 bootdevicesubstituting bootdevice for
your real
boot device such as ad0 (first IDE
disk), ad4 (first IDE disk on
auxiliary controller), da0 (first
SCSI disk), etc.My A, T, or X series IBM Thinkpad locks up when I first
booted up my FreeBSD installation. How can I solve this?A bug in early revisions of IBM's BIOS on these machines
mistakenly identifies the FreeBSD partition as a potential FAT
suspend-to-disk partition. When the BIOS tries to parse the
FreeBSD partition it hangs.According to IBMIn an e-mail from Keith
Frechette
kfrechet@us.ibm.com., the
following model/BIOS release numbers incorporate the fix.ModelBIOS revisionT20IYET49WW or laterT21KZET22WW or laterA20pIVET62WW or laterA20mIWET54WW or laterA21pKYET27WW or laterA21mKXET24WW or laterA21eKUET30WWIt has been reported that later IBM BIOS revisions may have
reintroduced the bug. This message
from Jacques Vidrine to the &a.mobile; describes a procedure
which may work if your newer IBM laptop does not boot FreeBSD
properly, and you can upgrade or downgrade the BIOS..If you have an earlier BIOS, and upgrading is not an option a
workaround is to install FreeBSD, change the partition ID FreeBSD
uses, and install new boot blocks that can handle the different
partition ID.First, you will need to restore the machine to a state where
it can get through its self-test screen. Doing this requires
powering up the machine without letting it find a FreeBSD
partition on its primary disk. One way is to remove the hard disk
and temporarily move it to an older ThinkPad (such as a ThinkPad
600) or a desktop PC with an appropriate conversion cable. Once
it is there, you can delete the FreeBSD partition and move the hard
disk back. The ThinkPad should now be in a bootable state
again.With the machine functional again, you can use the workaround
procedure described here to get a working FreeBSD
installation.Download boot1 and
boot2 from http://people.freebsd.org/~bmah/ThinkPad/.
+ url="http://people.FreeBSD.org/~bmah/ThinkPad/">http://people.FreeBSD.org/~bmah/ThinkPad/.
Put these files somewhere you will be able to retrieve them
later.Install FreeBSD as normal on to the ThinkPad.
Do not use Dangerously
Dedicated mode. Do not
reboot when the install has finished.Either switch to the Emergency Holographic
Shell (ALTF4) or start a
fixit shell.Use &man.fdisk.8; to change the FreeBSD partition ID from
165 to 166 (this is the
type used by OpenBSD).Bring the boot1 and
boot2 files to the local
filesystem.Use &man.disklabel.8; to write boot1
and boot2 to your FreeBSD slice.&prompt.root; disklabel -B -b boot1 -s boot2 ad0snn is the number of the slice
where you installed FreeBSD.Reboot. At the boot prompt you will be given the option
of booting OpenBSD. This will actually
boot FreeBSD.Getting this to work in the case where you want to dual boot
OpenBSD and FreeBSD on the same laptop is left as an exercise for
the reader.Can I install on a disk with bad blocks?Prior to 3.0, FreeBSD included a utility known as
bad144, which automatically remapped bad
blocks. Because modern IDE drives perform this function
themselves, bad144 has been removed from the
FreeBSD source tree. If you wish to install FreeBSD 3.0 or
later, we strongly suggest you purchase a newer disk drive. If
you do not wish to do this, you must run FreeBSD 2.x.If you are seeing bad block errors with a modern IDE
drive, chances are the drive is going to die very soon (the
drive's internal remapping functions are no longer sufficient
to fix the bad blocks, which means the disk is heavily
corrupted); we suggest you buy a new hard drive.If you have a SCSI drive with bad blocks, see
this answer.Strange things happen when I boot the install floppy!
What is happening?If you are seeing things like the machine grinding to a halt
or spontaneously rebooting when you try to boot the install
floppy, here are three questions to ask yourself:-Did you use a new, freshly-formatted, error-free floppy
(preferably a brand-new one straight out of the box, as
opposed to the magazine coverdisk that has been lying under
the bed for the last three years)?Did you download the floppy image in binary (or image)
mode? (do not be embarrassed, even the best of us have
accidentally downloaded a binary file in ASCII mode at
least once!)If you are using Windows95 or Win98 did you run
fdimage or rawrite in
pure DOS mode? These OS's can interfere with programs that
write directly to hardware, which the disk creation program
does; even running it inside a DOS shell in the GUI can
cause this problem.There have also been reports of Netscape causing problems
when downloading the boot floppy, so it is probably best to use
a different FTP client if you can.I booted from my ATAPI CDROM, but the install program says no
CDROM is found. Where did it go?The usual cause of this problem is a mis-configured CDROM
drive. Many PCs now ship with the CDROM as the slave device on
the secondary IDE controller, with no master device on that
controller. This is illegal according to the ATAPI specification,
but Windows plays fast and loose with the specification, and the
BIOS ignores it when booting. This is why the BIOS was able to
see the CDROM to boot from it, but why FreeBSD cannot see it to
complete the install.Reconfigure your system so that the CDROM is either the
master device on the IDE controller it is attached to, or make
sure that it is the slave on an IDE controller that also has a
master device.Why can I not install from tape?If you are installing 2.1.7R from tape, you must create
the tape using a tar blocksize of 10 (5120 bytes). The default
tar blocksize is 20 (10240 bytes), and tapes created using this
default size cannot be used to install 2.1.7R; with these
tapes, you will get an error that complains about the record
size being too big.Can I install on my laptop over PLIP (Parallel Line
IP)?Connect the two computers using a Laplink parallel cable
to use this feature:
See also this note on the
Mobile Computing page.Which geometry should I use for a disk drive?By the geometry of a disk, we mean the
number of cylinders, heads and sectors/track on a disk - I will
refer to this as C/H/S for convenience. This is how the PC's
BIOS works out which area on a disk to read/write from.This seems to cause a lot of confusion for some reason.
First of all, the physical geometry of a
SCSI drive is totally irrelevant, as FreeBSD works in term of
disk blocks. In fact, there is no such thing as
the physical geometry, as the sector
density varies across the disk - what manufacturers claim is
the physical geometry is usually the
geometry that they have worked out results in the least wasted
space. For IDE disks, FreeBSD does work in terms of C/H/S, but
all modern drives will convert this into block references
internally as well.All that matters is the logical
geometry - the answer that the BIOS gets when it asks
what is your geometry? and then uses to access
the disk. As FreeBSD uses the BIOS when booting, it is very
important to get this right. In particular, if you have more
than one operating system on a disk, they must all agree on the
geometry, otherwise you will have serious problems
booting!For SCSI disks, the geometry to use depends on whether
extended translation support is turned on in your controller
(this is often referred to as support for DOS disks
>1GB or something similar). If it is turned off, then
use N cylinders, 64 heads and 32
sectors/track, where N is the
capacity of the disk in MB. For example, a 2GB disk should
pretend to have 2048 cylinders, 64 heads and 32
sectors/track.If it is turned on (it is often supplied
this way to get around certain limitations in MSDOS) and the
disk capacity is more than 1GB, use M cylinders, 63 sectors per
track (not 64), and 255 heads, where 'M' is the disk capacity
in MB divided by 7.844238 (!). So our example 2GB drive would
have 261 cylinders, 63 sectors per track and 255 heads.If you are not sure about this, or FreeBSD fails to detect
the geometry correctly during installation, the simplest way
around this is usually to create a small DOS partition on the
disk. The correct geometry should then be detected (and you can
always remove the DOS partition in the partition editor if you
do not want to keep it, or leave it around for programming
network cards and the like).Alternatively, there is a freely available utility
distributed with FreeBSD called pfdisk.exe
(located in the tools subdirectory on the
FreeBSD CDROM or on the various FreeBSD FTP sites) which can be
used to work out what geometry the other operating systems on
the disk are using. You can then enter this geometry in the
partition editor.Are there any restrictions on how I divide the disk up?Yes. You must make sure that your root partition is below
1024
cylinders so the BIOS can boot the kernel from it. (Note that
this is a limitation in the PC's BIOS, not FreeBSD).For a SCSI drive, this will normally imply that the root
partition will be in the first 1024MB (or in the first 4096MB
if extended translation is turned on - see previous question).
For IDE, the corresponding figure is 504MB.Is FreeBSD compatible with any disk managers?FreeBSD recognizes the Ontrack Disk Manager and makes
allowances for it. Other disk managers are not supported.If you just want to use the disk with FreeBSD you do not
need a disk manager. Just configure the disk for as much space
as the BIOS can deal with (usually 504 megabytes), and FreeBSD
should figure out how much space you really have. If you are
using an old disk with an MFM controller, you may need to
explicitly tell FreeBSD how many cylinders to use.If you want to use the disk with FreeBSD and another
operating system, you may be able to do without a disk manager:
just make sure the FreeBSD boot partition and the slice for
the other operating system are in the first 1024 cylinders. If
you are reasonably careful, a 20 megabyte boot partition should
be plenty.When I boot FreeBSD I get Missing Operating
System. What is happening?This is classically a case of FreeBSD and DOS or some other
OS conflicting over their ideas of disk geometry. You will have to reinstall
FreeBSD, but obeying the instructions given above will almost
always get you going.Why can I not get past the boot manager's F?
prompt?This is another symptom of the problem described in the
preceding question. Your BIOS geometry and FreeBSD geometry
settings do not agree! If your controller or BIOS supports
cylinder translation (often marked as >1GB drive
support), try toggling its setting and reinstalling
FreeBSD.Do I need to install the complete sources?In general, no. However, we would strongly recommend that
you install, at a minimum, the base source
kit, which includes several of the files mentioned here, and
the sys (kernel) source kit, which includes
sources for the kernel. There is nothing in the system which
requires the presence of the sources to operate, however,
except for the kernel-configuration program &man.config.8;.
With the exception of the kernel sources, our build structure
is set up so that you can read-only mount the sources from
elsewhere via NFS and still be able to make new binaries.
(Because of the kernel-source restriction, we recommend that
you not mount this on /usr/src directly,
but rather in some other location with appropriate symbolic
links to duplicate the top-level structure of the source
tree.)Having the sources on-line and knowing how to build a
system with them will make it much easier for you to upgrade
to future releases of FreeBSD.To actually select a subset of the sources, use the Custom
menu item when you are in the Distributions menu of the
system installation tool.Do I need to build a kernel?Building a new kernel was originally pretty much a required
step in a FreeBSD installation, but more recent releases have
benefited from the introduction of a much friendlier kernel
configuration tool. When at the FreeBSD boot prompt (boot:),
use the flag and you will be dropped into a
visual configuration screen which allows you to configure the
kernel's settings for most common ISA cards.It is still recommended that you eventually build a new
kernel containing just the drivers that you need, just to save a
bit of RAM, but it is no longer a strict requirement for most
systems.Should I use DES passwords, or MD5, and how do I specify
which form my users receive?The default password format on FreeBSD is to use
MD5-based passwords. These are believed to
be more secure than the traditional Unix password format, which
used a scheme based on the DES algorithm.
DES passwords are still available if you need to share your
password file with legacy operating systems which still use the
less secure password format (they are available if you choose
to install the crypto distribution in
sysinstall, or by installing the crypto sources if building
from source). Which password format to use for new passwords is
controlled by the passwd_format login capability
in /etc/login.conf, which takes values of
either des (if available) or md5.
See the &man.login.conf.5; manpage for more information about login
capabilities.Why does the boot floppy start, but hang at the
Probing Devices... screen?If you have a IDE Zip or Jaz drive installed, remove it
and try again. The boot floppy can get confused by the drives.
After the system is installed you can reconnect the drive.
Hopefully this will be fixed in a later release.Why do I get a panic: can't mount root
error when rebooting the system after installation?This error comes from confusion between the boot block's
and the kernel's understanding of the disk devices. The error
usually manifests on two-disk IDE systems, with the hard disks
arranged as the master or single device on separate IDE
controllers, with FreeBSD installed on the secondary IDE
controller. The boot blocks think the system is installed on
wd1 (the second BIOS disk) while the kernel assigns the first
disk on the secondary controller device wd2. After the device
probing, the kernel tries to mount what the boot blocks think
is the boot disk, wd1, while it is really wd2, and
fails.To fix the problem, do one of the following:For FreeBSD 3.3 and later, reboot the system and hit
Enter at the Booting kernel
in 10 seconds; hit [Enter] to interrupt prompt.
This will drop you into the boot loader.Then type
set root_disk_unit="disk_number"
. disk_number
will be 0 if FreeBSD is installed on
the master drive on the first IDE controller,
1 if it is installed on the slave on
the first IDE controller, 2 if it is
installed on the master of the second IDE controller, and
3 if it is installed on the slave of
the second IDE controller.Then type boot, and your system
should boot correctly.To make this change permanent (ie so you do not have to
do this every time you reboot or turn on your FreeBSD
machine), put the line
root_disk_unit="disk_number" in /boot/loader.conf.local
.If using FreeBSD 3.2 or earlier, at the Boot: prompt,
enter 1:wd(2,a)kernel and press Enter.
If the system starts, then run the command
echo "1:wd(2,a)kernel" > /boot.config
to make it the default boot string.Move the FreeBSD disk onto the primary IDE controller,
so the hard disks are consecutive.Rebuild
your kernel, modify the wd configuration lines to
read:controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr
disk wd0 at wdc0 drive 0
# disk wd1 at wdc0 drive 1 # comment out this line
controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr
disk wd1 at wdc1 drive 0 # change from wd2 to wd1
disk wd2 at wdc1 drive 1 # change from wd3 to wd2Install the new kernel. If you moved your disks and
wish to restore the previous configuration, replace the
disks in the desired configuration and reboot. Your
system should boot successfully.What are the limits for memory?For memory, the limit is 4 gigabytes. This configuration
has been tested, see wcarchive's
configuration for more details. If you plan to install
this much memory into a machine, you need to be careful. You will
probably want to use ECC memory and to reduce capacitive
loading use 9 chip memory modules versus 18 chip memory
modules.What are the limits for ffs filesystems?For ffs filesystems, the maximum theoretical limit is 8
terabytes (2G blocks), or 16TB for the default block size of
8K. In practice, there is a soft limit of 1 terabyte, but with
modifications filesystems with 4 terabytes are possible (and
exist).The maximum size of a single ffs file is approximately 1G
blocks (4TB) if the block size is 4K.
Maximum file sizesfs block size2.2.7-stable3.0-currentworksshould work4K4T-14T-14T-1>4T8K>32G8T-1>32G32T-116K>128G16T-1>128G32T-132K>512G32T-1>512G64T-164K>2048G64T-1>2048G128T-1
When the fs block size is 4K, triple indirect blocks work
and everything should be limited by the maximum fs block number
that can be represented using triple indirect blocks (approx.
1K^3 + 1K^2 + 1K), but everything is limited by a (wrong) limit
of 1G-1 on fs block numbers. The limit on fs block numbers
should be 2G-1. There are some bugs for fs block numbers near
2G-1, but such block numbers are unreachable when the fs block
size is 4K.For block sizes of 8K and larger, everything should be
limited by the 2G-1 limit on fs block numbers, but is actually
limited by the 1G-1 limit on fs block numbers, except under
-STABLE triple indirect blocks are unreachable, so the limit is
the maximum fs block number that can be represented using
double indirect blocks (approx. (blocksize/4)^2 +
(blocksize/4)), and under -CURRENT exceeding this limit may
cause problems. Using the correct limit of 2G-1 blocks does
cause problems.How can I put 1TB files on my floppy?I keep several virtual ones on floppies :-). The maximum
file size is not closely related to the maximum disk size. The
maximum disk size is 1TB. It is a feature that the file size
can be larger than the disk size.The following example creates a file of size 8T-1 using a
whole 32K of disk space (3 indirect blocks and 1 data block) on
a small root partition. The dd command requires a dd that works
with large files.&prompt.user; cat foo
df .
dd if=/dev/zero of=z bs=1 seek=`echo 2^43 - 2 | bc` count=1
ls -l z
du z
df .
&prompt.user; sh foo
Filesystem 1024-blocks Used Avail Capacity Mounted on
/dev/da0a 64479 27702 31619 47% /
1+0 records in
1+0 records out
1 bytes transferred in 0.000187 secs (5346 bytes/sec)
-rw-r--r-- 1 bde bin 8796093022207 Sep 7 16:04 z
32 z
Filesystem 1024-blocks Used Avail Capacity Mounted on
/dev/da0a 64479 27734 31587 47% /Bruce Evans, September 1998Why do I get an error message,
archsw.readin.failed after compiling
and booting a new kernel?You can boot by specifying the kernel directly at the second
stage, pressing any key when the | shows up before loader is
started. More specifically, you have upgraded the source for
your kernel, and installed a new kernel builtin from them
without making world. This is not
supported. Make world.How do I upgrade from 3.X -> 4.X?We strongly recommend that you use
binary snapshots to do this. 4-STABLE snapshots are available at
releng4.FreeBSD.org.
+ URL="ftp://releng4.FreeBSD.org/">ftp://releng4.FreeBSD.org/.
If you wish to upgrade using source, please see the FreeBSD
+ URL="../handbook/cutting-edge.html">FreeBSD
Handbook for more information.Upgrading via source is never recommended for new
users, and upgrading from 3.X to 4.X is even less so; make sure
you have read the instructions carefully before attempting to
upgrade via source.What are these security profiles?A security profile is a set of configuration
options that attempts to achieve the desired ratio of security
to convenience by enabling and disabling certain programs and
other settings. The more severe the security profile, the
fewer programs will be enabled by default. This is one of the
basic principles of security: do not run anything except what
you must.Please note that the security profile is just a default
setting. All programs can be enabled and disabled after you
have installed FreeBSD by editing or adding the appropriate
line(s) to /etc/rc.conf. For more
information, please see the &man.rc.conf.5; manual page.The following table describes what each of the security
profiles does. The columns are the choices you have for a
security profile, and the rows are the program or feature that
the profile enables or disables.
Possible security profilesExtremeModerate&man.sendmail.8;NOYES&man.sshd.8;NOYES&man.portmap.8;NOMAYBE
The portmapper is enabled if the machine has
been configured as an NFS client or server earlier
in the installation.NFS serverNOYES&man.securelevel.8;YES (2)
If you choose a security profile that sets the
securelevel (Extreme or High), you must be aware
of the implications. Please read the &man.init.8;
manual page and pay particular attention to the
meanings of the security levels, or you may have
significant trouble later!NO
The security profile is not a silver bullet! Even if you use the
extreme setting, you need to keep up with security
issues by reading an appropriate mailing
list, using good passwords and passphrases, and
generally adhering to good security practices. It simply
sets up the desired security to convenience ratio out of
the box.The security profile mechanism is meant to be used
when you first install FreeBSD. If you already have
FreeBSD installed, it would probably be more beneficial to
simply enable or disable the desired functionality. If
you really want to use a security profile, you can re-run
&man.sysinstall.8; to set it.Hardware compatibilityDoes FreeBSD support architectures other than the
x86?Yes. FreeBSD currently runs on both Intel x86 and
DEC (now Compaq) Alpha architectures. Interest has also
been expressed in a port of FreeBSD to the SPARC architecture,
join the freebsd-sparc@FreeBSD.org mailing list if you are interested
in joining that project. Most recent additions to the list of
upcoming platforms are IA-64 and PowerPC, join the
freebsd-ia64@FreeBSD.org and/or
freebsd-ppc@FreeBSD.org mailing lists for more information.
For general discussion on new architectures, join
the freebsd-platforms@FreeBSD.org
mailing list.If your machine has a different architecture and you need
something right now, we suggest you look at NetBSD or OpenBSD.What kind of hard drives does FreeBSD support?FreeBSD supports EIDE and SCSI drives (with a compatible
controller; see the next section), and all drives using the
original Western Digital interface (MFM, RLL,
ESDI, and of course IDE). A few ESDI controllers that use
proprietary interfaces may not work: stick to WD1002/3/6/7
interfaces and clones.Which SCSI controllers are supported?See the complete list in the Handbook.Which CDROM drives are supported by FreeBSD?Any SCSI drive connected to a supported controller is
supported.The following proprietary CDROM interfaces are also
supported:Mitsumi LU002 (8bit), LU005 (16bit) and FX001D
(16bit 2x Speed).Sony CDU 31/33ASound Blaster Non-SCSI CDROMMatsushita/Panasonic CDROMATAPI compatible IDE CDROMsAll non-SCSI cards are known to be extremely slow compared
to SCSI drives, and some ATAPI CDROMs may not work.As of 2.2 the FreeBSD CDROM from the FreeBSD Mall supports
booting directly from the CD.Which CD-RW drives are supported by FreeBSD?FreeBSD supports any ATAPI-compatible IDE CD-R or CD-RW
drive. For FreeBSD versions 4.0 and later, see the man page for
&man.burncd.8;. For earlier FreeBSD versions, see the examples
in /usr/share/examples/atapi.FreeBSD also supports any SCSI CD-R or CD-RW drives.
Install and use the cdrecord command from the
ports or packages system, and make sure that you have the
pass device compiled in your
kernel.Does FreeBSD support ZIP drives?FreeBSD supports the SCSI ZIP drive out of the box, of
course. The ZIP drive can only be set to run at SCSI target IDs
5 or 6, but if your SCSI host adapter's BIOS supports it you
can even boot from it. It is not clear which host
adapters support booting from targets other than 0 or 1,
so you will have to consult your adapter's documentation
if you would like to use this feature.ATAPI (IDE) Zip drives are supported in FreeBSD 2.2.6 and
later releases.FreeBSD has contained support for Parallel Port Zip Drives
since version 3.0. If you are using a sufficiently up to date
version, then you should check that your kernel contains the
scbus0, da0,
ppbus0, and
vp0 drivers (the GENERIC kernel
contains everything except vp0). With
all these drivers present, the Parallel Port drive should be
available as /dev/da0s4. Disks can be
mounted using mount /dev/da0s4 /mnt OR (for
dos disks) mount_msdos /dev/da0s4 /mnt as
appropriate.Also check out this note on removable
drives, and this note on
formatting.Does FreeBSD support JAZ, EZ and other removable
drives?Apart from the IDE version of the EZ drive, these are all
SCSI devices, so they should all look like SCSI disks to
FreeBSD, and the IDE EZ should look like an IDE drive.I am not sure how well FreeBSD supports
changing the media out while running. You will of course need
to dismount the drive before swapping media, and make sure that
any external units are powered on when you boot the system so
FreeBSD can see them.See this note on
formatting.Which multi-port serial cards are supported by
FreeBSD?There is a list of these in the Miscellaneous
+ URL="../handbook/install.html#INSTALL-MISC">Miscellaneous
devices section of the handbook.Some unnamed clone cards have also been known to work,
especially those that claim to be AST compatible.Check the &man.sio.4;
man page to get more information on configuring such cards.Does FreeBSD support my USB keyboard?USB device support was added to FreeBSD 3.1. However, it
is still in preliminary state and may not always work as of
version 3.2. If you want to experiment with the USB keyboard
support, follow the procedure described below.Use FreeBSD 3.2 or later.Add the following lines to your kernel configuration
file, and rebuild the kernel.device uhci
device ohci
device usb
device ukbd
options KBD_INSTALL_CDEVIn versions of FreeBSD before 4.0, use this
instead:controller uhci0
controller ohci0
controller usb0
controller ukbd0
options KBD_INSTALL_CDEVGo to the /dev directory and create
device nodes as follows:&prompt.root; cd /dev
&prompt.root; ./MAKEDEV kbd0 kbd1Edit /etc/rc.conf and add the
following lines:usbd_enable="YES"
usbd_flags=""After the system is rebooted, the AT keyboard becomes
/dev/kbd0 and the USB keyboard becomes
/dev/kbd1, if both are connected to the
system. If there is the USB keyboard only, it will be
/dev/ukbd0.If you want to use the USB keyboard in the console, you
have to explicitly tell the console driver to use the existing
USB keyboard. This can be done by running the following
command as a part of system initialization.&prompt.root; kbdcontrol -k /dev/kbd1 < /dev/ttyv0 > /dev/nullNote that if the USB keyboard is the only keyboard, it is
accessed as /dev/kbd0, thus, the command
should look like:&prompt.root; kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null/etc/rc.i386 is a good place to add the
above command.Once this is done, the USB keyboard should work in the X
environment as well without any special settings.Hot-plugging and unplugging of the USB keyboard may not
work quite right yet. It is a good idea to connect the keyboard
before you start the system and leave it connected until the
system is shutdown to avoid troubles.See the &man.ukbd.4; man page for more information.I have an unusual bus mouse. How do I set it up?FreeBSD supports the bus mouse and the InPort bus mouse
from such manufactures as Microsoft, Logitech and ATI. The bus
device driver is compiled in the GENERIC kernel by default in
FreeBSD versions 2.X, but not included in version 3.0 or later.
If you are building a custom kernel with the bus mouse driver,
make sure to add the following line to the kernel config
fileIn FreeBSD 3.0 or before, add:device mse0 at isa? port 0x23c tty irq5 vector mseintrIn FreeBSD 3.X, the line should be:device mse0 at isa? port 0x23c tty irq5And in FreeBSD 4.X and later, the line should read:device mse0 at isa? port 0x23c irq5Bus mice usually comes with dedicated interface cards.
These cards may allow you to set the port address and the IRQ
number other than shown above. Refer to the manual of your
mouse and the &man.mse.4; man page for more information.How do I use my PS/2 (mouse port or
keyboard) mouse?If you are running a post-2.2.5 version of FreeBSD, the
necessary driver, psm, is included and
enabled in the kernel. The kernel should detect your PS/2 mouse
at boot time.If you are running a previous but relatively recent version
of FreeBSD (2.1.x or better) then you can simply enable it in
the kernel configuration menu at installation time, otherwise
later with at the boot:
prompt. It is disabled by default, so you will need to enable
it explicitly.If you are running an older version of FreeBSD then you will
have to add the following lines to your kernel configuration
file and compile a new kernel.In FreeBSD 3.0 or earlier, the line should be:device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintrIn FreeBSD 3.1 or later, the line should be:device psm0 at isa? tty irq 12In FreeBSD 4.0 or later, the line should be:device psm0 at atkbdc? irq 12See the Handbook entry on
configuring the kernel if you have no experience with
building kernels.Once you have a kernel detecting
psm0 correctly at boot time, make sure
that an entry for psm0 exists in
/dev. You can do this by typing:&prompt.root; cd /dev; sh MAKEDEV psm0when logged in as root.Is it possible to make use of a mouse in any way outside
the X Window system?If you are using the default console driver, syscons, you
can use a mouse pointer in text consoles to cut & paste
text. Run the mouse daemon, moused, and turn on the mouse
pointer in the virtual console:&prompt.root; moused -p /dev/xxxx -t yyyy
&prompt.root; vidcontrol -m onWhere xxxx is the mouse device
name and yyyy is a protocol type for
the mouse. See the &man.moused.8; man page for supported
protocol types.You may wish to run the mouse daemon automatically when the
system starts. In version 2.2.1, set the following variables in
/etc/sysconfig.mousedtype="yyyy"
mousedport="xxxx"
mousedflags=""In versions 2.2.2 to 3.0, set the following variables in
/etc/rc.conf.moused_type="yyyy"
moused_port="xxxx"
moused_flags=""In 3.1 and later, assuming you have a PS/2 mouse, all you
need to is add moused_enable="YES" to
/etc/rc.conf.In addition, if you would like to be able to use the mouse
daemon on all virtual terminals instead of just console at
boot-time, add the following to
/etc/rc.conf.allscreens_flags="-m on"Staring from FreeBSD 2.2.6, the mouse daemon is capable of
determining the correct protocol type automatically unless the
mouse is a relatively old serial mouse model. Specify
auto the protocol to invoke automatic
detection.When the mouse daemon is running, access to the mouse
needs to be coordinated between the mouse daemon and other
programs such as the X Window. Refer to another section on this
issue.How do I cut and paste text with mouse in the text
console?Once you get the mouse daemon running (see
previous section), hold down the
button 1 (left button) and move the mouse to select a region of
text. Then, press the button 2 (middle button) or the button 3
(right button) to paste it at the text cursor.In versions 2.2.6 and later, pressing the button 2 will
paste the text. Pressing the button 3 will
extend the selected region of text. If your
mouse does not have the middle button, you may wish to emulate
it or remap buttons using moused options. See the
&man.moused.8; man page for details.Does FreeBSD support any USB mice?USB device support was added to FreeBSD 3.1. However, it
is still in a preliminary state and may not always work as of
version 3.2. If you want to experiment with the USB mouse
support, follow the procedure described below.Use FreeBSD 3.2 or later.Add the following lines to your kernel configuration
file, and rebuild the kernel.device uhci
device ohci
device usb
device umsIn versions of FreeBSD before 4.0, use this
instead:controller uhci0
controller ohci0
controller usb0
device ums0Go to the /dev directory and
create a device node as follows:&prompt.root; cd /dev
&prompt.root; ./MAKEDEV ums0Edit /etc/rc.conf and add the
following lines:moused_enable="YES"
moused_type="auto"
moused_port="/dev/ums0"
moused_flags=""
usbd_enable="YES"
usbd_flags=""See the previous section
for more detailed discussion on moused.In order to use the USB mouse in the X session, edit
XF86Config. If you are using XFree86
3.3.2 or later, be sure to have the following lines in the
Pointer section:Device "/dev/sysmouse"
Protocol "Auto"If you are using earlier versions of XFree86, be sure to
have the following lines in the Pointer
section:Device "/dev/sysmouse"
Protocol "SysMouse"Refer to another section
on the mouse support in the X environment.Hot-plugging and unplugging of the USB mouse may not work
quite right yet. It is a good idea connect the mouse before you
start the system and leave it connected until the system is
shutdown to avoid trouble.My mouse has a fancy wheel and buttons. Can I use them in
FreeBSD?The answer is, unfortunately, It depends.
These mice with additional features require specialized driver
in most cases. Unless the mouse device driver or the user
program has specific support for the mouse, it will act just
like a standard two, or three button mouse.For the possible usage of wheels in the X Window
environment, refer to that
section.Why does my wheel-equipped PS/2 mouse cause my mouse cursor
to jump around the screen?The PS/2 mouse driver psm in FreeBSD versions 3.2 or
earlier has difficulty with some wheel mice, including Logitech
model M-S48 and its OEM siblings. Apply the following patch to
/sys/i386/isa/psm.c and rebuild the
kernel.Index: psm.c
===================================================================
RCS file: /src/CVS/src/sys/i386/isa/Attic/psm.c,v
retrieving revision 1.60.2.1
retrieving revision 1.60.2.2
diff -u -r1.60.2.1 -r1.60.2.2
--- psm.c 1999/06/03 12:41:13 1.60.2.1
+++ psm.c 1999/07/12 13:40:52 1.60.2.2
@@ -959,14 +959,28 @@
sc->mode.packetsize = vendortype[i].packetsize;
/* set mouse parameters */
+#if 0
+ /*
+ * A version of Logitech FirstMouse+ won't report wheel movement,
+ * if SET_DEFAULTS is sent... Don't use this command.
+ * This fix was found by Takashi Nishida.
+ */
i = send_aux_command(sc->kbdc, PSMC_SET_DEFAULTS);
if (verbose >= 2)
printf("psm%d: SET_DEFAULTS return code:%04x\n", unit, i);
+#endif
if (sc->config & PSM_CONFIG_RESOLUTION) {
sc->mode.resolution
= set_mouse_resolution(sc->kbdc,
- (sc->config & PSM_CONFIG_RESOLUTION) - 1);
+ (sc->config & PSM_CONFIG_RESOLUTION) - 1);
+ } else if (sc->mode.resolution >= 0) {
+ sc->mode.resolution
+ = set_mouse_resolution(sc->kbdc, sc->dflt_mode.resolution);
+ }
+ if (sc->mode.rate > 0) {
+ sc->mode.rate = set_mouse_sampling_rate(sc->kbdc, sc->dflt_mode.rate);
}
+ set_mouse_scaling(sc->kbdc, 1);
/* request a data packet and extract sync. bits */
if (get_mouse_status(sc->kbdc, stat, 1, 3) < 3) {Versions later than 3.2 should be all right.How do I use the mouse/trackball/touchpad on my
laptop?Please refer to the answer to
the previous question. And check out
this note on the Mobile Computing
page.What types of tape drives are supported?FreeBSD supports SCSI and QIC-36 (with a QIC-02 interface).
This includes 8-mm (aka Exabyte) and DAT drives.Some of the early 8-mm drives are not quite compatible
with SCSI-2, and may not work well with FreeBSD.Does FreeBSD support tape changers?FreeBSD 2.2 supports SCSI changers using the
&man.ch.4;
device and the
&man.chio.1;
command. The details of how you actually control the changer
can be found in the
&man.chio.1;
man page.If you are not using AMANDA
or some other product that already understands changers,
remember that they only know how to move a tape from one
point to another, so you need to keep track of which slot a
tape is in, and which slot the tape currently in the drive
needs to go back to.Which sound cards are supported by FreeBSD?FreeBSD supports the SoundBlaster, SoundBlaster Pro,
SoundBlaster 16, Pro Audio Spectrum 16, AdLib and Gravis
UltraSound sound cards. There is also limited support for
MPU-401 and compatible MIDI cards. Cards conforming to the
Microsoft Sound System specification are also supported through
the pcm driver.This is only for sound! This driver does not support
CDROMs, SCSI or joysticks on these cards, except for the
SoundBlaster. The SoundBlaster SCSI interface and some
non-SCSI CDROMS are supported, but you cannot boot off this
device.Workarounds for no sound from es1370 with pcm driver?You can run the following command every time the machine
booted up:&prompt.root; mixer pcm 100 vol 100 cd 100Which network cards does FreeBSD support?See the
+ URL="../handbook/install.html#INSTALL-NICS">
Ethernet cards section of the handbook for a more
complete list.I do not have a math co-processor - is that bad?This will only affect 386/486SX/486SLC owners - other
machines will have one built into the CPU.In general this will not cause any problems, but there are
circumstances where you will take a hit, either in performance
or accuracy of the math emulation code (see the section on FP emulation). In particular, drawing
arcs in X will be VERY slow. It is highly recommended that you
buy a math co-processor; it is well worth it.Some math co-processors are better than others. It
pains us to say it, but nobody ever got fired for buying
Intel. Unless you are sure it works with FreeBSD, beware of
clones.What other devices does FreeBSD support?See the Handbook
for the list of other devices supported.Does FreeBSD support power management on my laptop?FreeBSD supports APM on certain machines. Please look in
the LINT kernel config file, searching for
the
APM
keyword. Further information can be found in &man.apm.4;.Why does my Micron system hang at boot time?Certain Micron motherboards have a non-conforming PCI BIOS
implementation that causes grief when FreeBSD boots because PCI
devices do not get configured at their reported addresses.Disable the Plug and Play Operating System
flag in the BIOS to work around this problem. More information
can be found at
http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micronWhy does FreeBSD not recognize my Adaptec SCSI
controller card?The newer AIC789x series Adaptec chips are supported under
the CAM SCSI framework which made it's debut in 3.0. Patches
against 2.2-STABLE are in
ftp://ftp.FreeBSD.org/pub/FreeBSD/development/cam/.
A CAM-enhanced boot floppy is available at
http://people.FreeBSD.org/~abial/cam-boot/.
In both cases read the README before beginning.How come FreeBSD cannot find my internal Plug & Play
modem?You will need to add the modem's PnP ID to the PnP ID
list in the serial driver. To enable Plug & Play support,
compile a new kernel with controller pnp0 in
the configuration file, then reboot the system. The kernel will
print the PnP IDs of all the devices it finds. Copy the PnP ID
from the modem to the table in
/sys/i386/isa/sio.c, at about line 2777.
Look for the string SUP1310 in the structure
siopnp_ids[] to find the table. Build the
kernel again, install, reboot, and your modem should be
found.You may have to manually configure the PnP devices using
the pnp command in the boot-time
configuration with a command likepnp 1 0 enable os irq0 3 drq0 0 port0 0x2f8to make the modem show.How do I get the boot: prompt to show on the serial
console?Build a kernel with
options COMCONSOLE.Create /boot.config and place
as the only text in the file.Unplug the keyboard from the system.See
/usr/src/sys/i386/boot/biosboot/README.serial
for information.Why doesn't my 3Com PCI network card work with my Micron
computer?Certain Micron motherboards have a non-conforming PCI BIOS
implementation that does not configure PCI devices at the
addresses reported. This causes grief when FreeBSD
boots.To work around this problem, disable the
Plug and Play Operating System flag in the
BIOS.More information on this problem is available at URL:
http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micronDoes FreeBSD support Symmetric Multiprocessing (SMP)?SMP is supported in 3.0-STABLE and later releases only.
SMP is not enabled in the GENERIC kernel,
so you will have to recompile your kernel to enable SMP. Take a
look at /sys/i386/conf/LINT to figure out
what options to put in your kernel config file.The boot floppy hangs on a system with an ASUS K7V
motherboard. How do I fix this?Go in to the BIOS setup and disable the boot virus
protection.TroubleshootingWhat do I do when I have bad blocks on my hard drive?With SCSI drives, the drive should be capable of re-mapping
these automatically. However, many drives are shipped with
this feature disabled, for some mysterious reason...To enable this, you will need to edit the first device page
mode, which can be done on FreeBSD by giving the command
(as root)&prompt.root; scsi -f /dev/rsd0c -m 1 -e -P 3and changing the values of AWRE and ARRE from 0 to 1:-AWRE (Auto Write Reallocation Enbld): 1
ARRE (Auto Read Reallocation Enbld): 1The following paragraphs were submitted by Ted Mittelstaedt
tedm@toybox.placo.com:For IDE drives, any bad block is usually a sign of
potential trouble. All modern IDE drives come with internal
bad-block remapping turned on. All IDE hard drive manufacturers
today offer extensive warranties and will replace drives with
bad blocks on them.If you still want to attempt to rescue an IDE drive with
bad blocks, you can attempt to download the IDE drive
manufacturer's IDE diagnostic program, and run this against the
drive. Sometimes these programs can be set to force the drive
electronics to rescan the drive for bad blocks and lock them
out.For ESDI, RLL and MFM drives, bad blocks are a normal part
of the drive and are no sign of trouble, generally. With a PC,
the disk drive controller card and BIOS handle the task of
locking out bad sectors. This is fine for operating systems
like DOS that use BIOS code to access the disk. However,
FreeBSD's disk driver does not go through BIOS, therefore a
mechanism, bad144, exists that replaces this functionality.
bad144 only works with the wd driver (which means it is not
supported in FreeBSD 4.0), it is NOT able to be used with SCSI.
bad144 works by entering all bad sectors found into a special
file.One caveat with bad144 - the bad block special file is
placed on the last track of the disk. As this file may possibly
contain a listing for a bad sector that would occur near the
beginning of the disk, where the /kernel file might be located,
it therefore must be accessible to the bootstrap program that
uses BIOS calls to read the kernel file. This means that the
disk with bad144 used on it must not exceed 1024 cylinders, 16
heads, and 63 sectors. This places an effective limit of 500MB
on a disk that is mapped with bad144.To use bad144, simply set the Bad Block
scanning to ON in the FreeBSD fdisk screen during the initial
install. This works up through FreeBSD 2.2.7. The disk must
have less than 1024 cylinders. It is generally recommended that
the disk drive has been in operation for at least 4 hours prior
to this to allow for thermal expansion and track
wandering.If the disk has more than 1024 cylinders (such as a large
ESDI drive) the ESDI controller uses a special translation mode
to make it work under DOS. The wd driver understands about
these translation modes, IF you enter the
translated geometry with the set
geometry command in fdisk. You must also NOT use the
dangerously dedicated mode of creating the
FreeBSD partition, as this ignores the geometry. Also, even
though fdisk will use your overridden geometry, it still knows
the true size of the disk, and will attempt to create a too
large FreeBSD partition. If the disk geometry is changed to the
translated geometry, the partition MUST be manually created
with the number of blocks.A quick trick to use is to set up the large ESDI disk with
the ESDI controller, boot it with a DOS disk and format it with
a DOS partition. Then, boot the FreeBSD install and in the
fdisk screen, read off and write down the blocksize and block
numbers for the DOS partition. Then, reset the geometry to the
same that DOS uses, delete the DOS partition, and create a
cooperative FreeBSD partition using the
blocksize you recorded earlier. Then, set the partition
bootable and turn on bad block scanning. During the actual
install, bad144 will run first, before any filesystems are
created. (you can view this with an Alt-F2) If it has any
trouble creating the badsector file, you have set too large a
disk geometry - reboot the system and start all over again
(including repartitioning and reformatting with DOS).If remapping is enabled and you are seeing bad blocks,
consider replacing the drive. The bad blocks will only get
worse as time goes on.How come FreeBSD does not recognize my Bustek 742a EISA
SCSI controller?This info is specific to the 742a but may also cover
other Buslogic cards. (Bustek = Buslogic)There are 2 general versions of the 742a
card. They are hardware revisions A-G, and revisions H -
onwards. The revision letter is located after the Assembly
number on the edge of the card. The 742a has 2 ROM chips on it,
one is the BIOS chip and the other is the Firmware chip.
FreeBSD does not care what version of BIOS chip you have but it
does care about what version of firmware chip. Buslogic will
send upgrade ROMS out if you call their tech support dept. The
BIOS and Firmware chips are shipped as a matched pair. You must
have the most current Firmware ROM in your adapter card for
your hardware revision.The REV A-G cards can only accept BIOS/Firmware sets up to
2.41/2.21. The REV H- up cards can accept the most current
BIOS/Firmware sets of 4.70/3.37. The difference between the
firmware sets is that the 3.37 firmware supports round
robinThe Buslogic cards also have a serial number on them. If
you have a old hardware revision card you can call the Buslogic
RMA department and give them the serial number and attempt to
exchange the card for a newer hardware revision. If the card is
young enough they will do so.FreeBSD 2.1 only supports Firmware revisions 2.21 onward.
If you have a Firmware revision older than this your card will
not be recognized as a Buslogic card. It may be recognized as
an Adaptec 1540, however. The early Buslogic firmware contains
an AHA1540 emulation mode. This is not a good
thing for an EISA card, however.If you have an old hardware revision card and you obtain
the 2.21 firmware for it, you will need to check the position
of jumper W1 to B-C, the default is A-B.How come FreeBSD does not detect my HP Netserver's SCSI
controller?This is basically a known problem. The EISA on-board SCSI
controller in the HP Netserver machines occupies EISA slot
number 11, so all the true EISA slots are in
front of it. Alas, the address space for EISA slots >= 10
collides with the address space assigned to PCI, and FreeBSD's
auto-configuration currently cannot handle this situation very
well.So now, the best you can do is to pretend there is no
address range clash :), by bumping the kernel option
EISA_SLOTS to a value of 12. Configure and
compile a kernel, as described in the Handbook entry on
configuring the kernel.Of course, this does present you with a chicken-and-egg
problem when installing on such a machine. In order to work
around this problem, a special hack is available inside
UserConfig. Do not use the
visual interface, but the plain command-line
interface there. Simply typeeisa 12
quitat the prompt, and install your system as usual. While
it is recommended you compile and install a custom kernel
anyway.Hopefully, future versions will have a proper fix for
this problem.You cannot use a
dangerously dedicated disk
with an HP Netserver. See this
note for more info.What is going on with my CMD640 IDE controller?It is broken. It cannot handle commands on both channels
simultaneously.There's a workaround available now and it is enabled
automatically if your system uses this chip. For the details
refer to the manual page of the disk driver (man 4 wd).If you are already running FreeBSD 2.2.1 or 2.2.2 with a
CMD640 IDE controller and you want to use the second channel,
build a new kernel with options "CMD640"
enabled. This is the default for 2.2.5 and later.I keep seeing messages like
ed1: timeout. What do these messages
mean?This is usually caused by an interrupt conflict (e.g.,
two boards using the same IRQ). FreeBSD prior to 2.0.5R used to
be tolerant of this, and the network driver would still
function in the presence of IRQ conflicts. However, with 2.0.5R
and later, IRQ conflicts are no longer tolerated. Boot with the
-c option and change the ed0/de0/... entry to match your
board.If you are using the BNC connector on your network card,
you may also see device timeouts because of bad termination. To
check this, attach a terminator directly to the NIC (with no
cable) and see if the error messages go away.Some NE2000 compatible cards will give this error if there
is no link on the UTP port or if the cable is disconnected.Why do I get Incorrect super block when
mounting a CDROM?You have to tell &man.mount.8;
the type of the device that you want to mount. By default,
&man.mount.8;
will assume the filesystem is of type ufs.
You want to mount a CDROM filesystem, and you do this by
specifying the option to
&man.mount.8;. This does, of course, assume that the
CDROM contains an ISO 9660 filesystem, which is what most CDROMs
have. As of 1.1R, FreeBSD automatically understands the Rock
Ridge (long filename) extensions as well.As an example, if you want to mount the CDROM device,
/dev/cd0c, under /mnt,
you would execute:&prompt.root; mount -t cd9660 /dev/cd0c /mntNote that your device name (/dev/cd0c
in this example) could be different, depending on the CDROM
interface. Note that the option just
causes the &man.mount.cd9660.8; command to be
executed, and so the above example could be shortened
to:&prompt.root; mount_cd9660 /dev/cd0c /mntWhy do I get Device not configured when
mounting a CDROM?This generally means that there is no CDROM in the CDROM
drive, or the drive is not visible on the bus. Feed the drive
something, and/or check its master/slave status if it is IDE
(ATAPI). It can take a couple of seconds for a CDROM drive to
notice that it has been fed, so be patient.Sometimes a SCSI CDROM may be missed because it had not
enough time to answer the bus reset. If you have a SCSI CDROM
please try to add the following symbol into your kernel
configuration file and recompile.options "SCSI_DELAY=15"Why do all non-English characters in filenames show up as
? on my CDs when mounted in FreeBSD?Most likely your CDROM uses the Joliet
extension for storing information about files and directories.
This extension specifies that all filenames are stored using
Unicode two-byte characters. Currently, efforts are under way
to introduce a generic Unicode interface into the FreeBSD
kernel, but since that is not ready yet, the CD9660 driver does
not have the ability to decode the characters in the
filenames.As a temporary solution, starting with FreeBSD 4.3, a
special hook has been added into the CD9660 driver to allow the
user to load an appropriate conversion table on the fly.
Modules for some of the common encodings are available via the
sysutils/cd9660_unicode port.My printer is ridiculously slow. What can I do?If it is parallel, and the only problem is that it is terribly
slow, try setting your printer port into polled
mode:&prompt.root; lptcontrol -pSome newer HP printers are claimed not to work correctly in
interrupt mode, apparently due to some (not yet exactly
understood) timing problem.Why do my programs occasionally die with
Signal 11 errors?Signal 11 errors are caused when your process has attempted
to access memory which the operating system has not granted it
access to. If something like this is happening at seemingly
random intervals then you need to start investigating things
very carefully.These problems can usually be attributed to either:If the problem is occurring only in a specific
application that you are developing yourself it is probably
a bug in your code.If it is a problem with part of the base FreeBSD system,
it may also be buggy code, but more often than not these
problems are found and fixed long before us general FAQ
readers get to use these bits of code (that is what -current
is for).In particular, a dead giveaway that this is not a FreeBSD
bug is if you see the problem when you are compiling a program,
but the activity that the compiler is carrying out changes
each time.For example, suppose you are running make
buildworld, and the compile fails while trying to
compile ls.c in to
ls.o. If you then run make
buildworld again, and the compile fails in the same
place then this is a broken build -- try updating your sources
and try again. If the compile fails elsewhere then this is
almost certainly hardware.What you should do:In the first case you can use a debugger e.g. gdb to find
the point in the program which is attempting to access a bogus
address and then fix it.In the second case you need to verify that it is not your
hardware at fault.Common causes of this include:Your hard disks might be overheating: Check the fans in
your case are still working, as your disk (and perhaps
other hardware might be overheating).The processor running is overheating: This might be
because the processor has been overclocked, or the fan on
the processor might have died. In either case you need to
ensure that you have hardware running at what it is
specified to run at, at least while trying to solve this
problem. i.e. Clock it back to the default settings.If you are overclocking then note that it is far cheaper
to have a slow system than a fried system that needs
replacing! Also the wider community is not often
sympathetic to problems on overclocked systems, whether you
believe it is safe or not.Dodgy memory: If you have multiple memory SIMMS/DIMMS
installed then pull them all out and try running the
machine with each SIMM or DIMM individually and narrow the
problem down to either the problematic DIMM/SIMM or perhaps
even a combination.Over-optimistic Motherboard settings: In your BIOS
settings, and some motherboard jumpers you have options to
set various timings, mostly the defaults will be
sufficient, but sometimes, setting the wait states on RAM
too low, or setting the RAM Speed: Turbo option, or
similar in the BIOS will cause strange behaviour. A
possible idea is to set to BIOS defaults, but it might be
worth noting down your settings first!Unclean or insufficient power to the motherboard. If you
have any unused I/O boards, hard disks, or CDROMs in your
system, try temporarily removing them or disconnecting the
power cable from them, to see if your power supply can
manage a smaller load. Or try another power supply,
preferably one with a little more power (for instance, if
your current power supply is rated at 250 Watts try one
rated at 300 Watts).You should also read the SIG11 FAQ (listed below) which has
excellent explanations of all these problems, albeit from a
Linux viewpoint. It also discusses how memory testing software
or hardware can still pass faulty memory.Finally, if none of this has helped it is possible that
you have just found a bug in FreeBSD, and you should follow the
instructions to send a problem report.There is an extensive FAQ on this at
the SIG11 problem FAQWhy does the screen go black and lose sync when I
boot?This is a known problem with the ATI Mach 64 video card.
The problem is that this card uses address
2e8, and the fourth serial port does too.
Due to a bug (feature?) in the &man.sio.4;
driver it will touch this port even if you do not have the
fourth serial port, and even if
you disable sio3 (the fourth port) which normally uses this
address.Until the bug has been fixed, you can use this
workaround:Enter at the boot prompt.
(This will put the kernel into configuration mode).Disable sio0,
sio1,
sio2 and
sio3 (all of them). This way
the sio driver does not get activated -> no
problems.Type exit to continue booting.If you want to be able to use your serial ports, you will
have to build a new kernel with the following modification: in
/usr/src/sys/i386/isa/sio.c find the one
occurrence of the string 0x2e8 and remove
that string and the preceding comma (keep the trailing comma).
Now follow the normal procedure of building a new
kernel.Even after applying these workarounds, you may still find
that the X Window System does not work properly. If this is the
case, make sure that the XFree86 version you are using is at
least XFree86 3.3.3 or higher. This version and upwards has
built-in support for the Mach64 cards and even a dedicated X
server for those cards.How come FreeBSD uses only 64 MB of RAM when my system has
128 MB of RAM installed?Due to the manner in which FreeBSD gets the memory size
from the BIOS, it can only detect 16 bits worth of Kbytes in
size (65535 Kbytes = 64MB) (or less... some BIOSes peg the
memory size to 16M). If you have more than 64MB, FreeBSD will
attempt to detect it; however, the attempt may fail.To work around this problem, you need to use the kernel
option specified below. There is a way to get complete memory
information from the BIOS, but we do not have room in the
bootblocks to do it. Someday when lack of room in the
bootblocks is fixed, we will use the extended BIOS functions to
get the full memory information...but for now we are stuck with
the kernel option.options "MAXMEM=n"Where n is your memory in
Kilobytes. For a 128 MB machine, you would want to use
131072.Why does FreeBSD 2.0 panic with
kmem_map too small!?The message may also be
mb_map too small!The panic indicates that the system ran out of virtual
memory for network buffers (specifically, mbuf clusters). You
can increase the amount of VM available for mbuf clusters by
adding:options "NMBCLUSTERS=n"to your kernel config file, where
n is a number in the range 512-4096,
depending on the number of concurrent TCP connections you need
to support. I would recommend trying 2048 - this should get rid of
the panic completely. You can monitor the number of mbuf
clusters allocated/in use on the system with
netstat
-m (see &man.netstat.1;). The default value for NMBCLUSTERS is 512 +
MAXUSERS * 16.Why do I get an error reading CMAP
busy when rebooting with a new
kernel?The logic that attempts to detect an out of date
/var/db/kvm_*.db files sometimes fails
and using a mismatched file can sometimes lead to panics.If this happens, reboot single-user and do:&prompt.root; rm /var/db/kvm_*.dbWhat does the message ahc0: brkadrint,
Illegal Host Access at seqaddr 0x0
mean?This is a conflict with an Ultrastor SCSI Host Adapter.During the boot process enter the kernel configuration
menu and disable
uha0,
which is causing the problem.Why does Sendmail give me an error reading
mail loops back to
myself?This is answered in the sendmail FAQ as follows:- * I'm getting "Local configuration error" messages, such as:
553 relay.domain.net config error: mail loops back to myself
554 <user@domain.net>... Local configuration error
How can I solve this problem?
You have asked mail to the domain (e.g., domain.net) to be
forwarded to a specific host (in this case, relay.domain.net)
by using an MX record, but the relay machine doesn't recognize
itself as domain.net. Add domain.net to /etc/sendmail.cw
(if you are using FEATURE(use_cw_file)) or add "Cw domain.net"
to /etc/sendmail.cf.
The current version of the sendmail
FAQ is no longer maintained with the sendmail release.
It is however regularly posted to comp.mail.sendmail,
comp.mail.misc, comp.mail.smail, comp.answers, and news.answers. You can also
receive a copy via email by sending a message to
mail-server@rtfm.mit.edu with the command
send usenet/news.answers/mail/sendmail-faq
as the body of the message.Why do full screen applications on remote machines
misbehave?The remote machine may be setting your terminal type
to something other than the cons25 terminal
type required by the FreeBSD console.There are a number of possible work-arounds for this
problem:After logging on to the remote machine, set your
TERM shell variable to ansi or
sco if the remote machine knows
about these terminal types.Use a VT100 emulator like
screen at the FreeBSD console.
screen offers you the ability
to run multiple concurrent sessions from one terminal,
and is a neat program in its own right. Each
screen window behaves like a
VT100 terminal, so the TERM variable at the remote end
should be set to vt100.Install the cons25 terminal
database entry on the remote machine. The way to do this
depends on the operating system on the remote machine.
The system administration manuals for the remote system
should be able to help you here.Fire up an X server at the FreeBSD end and login to
the remote machine using an X based terminal emulator
such as xterm or
rxvt. The TERM variable at the remote
host should be set to xterm or
vt100.Why does my machine print
calcru: negative time...?This can be caused by various hardware and/or software
ailments relating to interrupts. It may be due to bugs but can
also happen by nature of certain devices. Running TCP/IP over
the parallel port using a large MTU is one good way to provoke
this problem. Graphics accelerators can also get you here, in
which case you should check the interrupt setting of the card
first.A side effect of this problem are dying processes with the
message SIGXCPU exceeded cpu time limit.For FreeBSD 3.0 and later from Nov 29, 1998 forward: If the
problem cannot be fixed otherwise the solution is to set
this sysctl variable:&prompt.root; sysctl -w kern.timecounter.method=1This means a performance impact, but considering the cause
of this problem, you probably will not notice. If the problem
persists, keep the sysctl set to one and set the
NTIMECOUNTER option in your kernel to
increasingly large values. If by the time you have reached
NTIMECOUNTER=20 the problem is not solved,
interrupts are too hosed on your machine for reliable
timekeeping.I see pcm0 not found or my sound card is
found as pcm1 but I have
device pcm0 in my kernel config file. What is
going on?This occurs in FreeBSD 3.x with PCI sound cards. The
pcm0 device is reserved exclusively for
ISA-based cards so, if you have a PCI card, then you will see
this error, and your card will appear as pcm1.
You cannot remove the warning by simply changing the
line in the kernel config file to device
pcm1 as this will result in
pcm1 being reserved for ISA cards and
your PCI card being found as pcm2 (along
with the warning pcm1 not found).
If you have a PCI sound card you will also have to make the
snd1 device rather than
snd0:&prompt.root; cd /dev
&prompt.root; ./MAKEDEV snd1This situation does not arise in FreeBSD 4.x as a lot
of work has been done to make it more
PnP-centric and the
pcm0 device is no longer reserved
exclusively for ISA cardsWhy is my PnP card no longer found (or found as
unknown) since upgrading to FreeBSD 4.x?FreeBSD 4.x is now much more PnP-centric
and this has had the side effect of some PnP devices (e.g. sound
cards and internal modems) not working even though they worked
under FreeBSD 3.x.The reasons for this behaviour are explained by the following
e-mail, posted to the freebsd-questions mailing list by Peter
Wemm, in answer to a question about an internal modem that was
no longer found after an upgrade to FreeBSD 4.x (the comments
in [] have been added to clarify the
context.
The PNP bios preconfigured it [the modem] and left it
laying around in port space, so [in 3.x] the old-style ISA
probes found it there.Under 4.0, the ISA code is much more PnP-centric. It was
possible [in 3.x] for an ISA probe to find a
stray device and then for the PNP device id to
match and then fail due to resource conflicts. So, it
disables the programmable cards first so this double probing
cannot happen. It also means that it needs to know the PnP
id's for supported PnP hardware. Making this more user
tweakable is on the TODO list.
To get the device working again requires finding its PnP id
and adding it to the list that the ISA probes use to identify
PnP devices. This is obtained using &man.pnpinfo.8; to probe the
device, for example this is the output from &man.pnpinfo.8; for
an internal modem:&prompt.root; pnpinfo
Checking for Plug-n-Play devices...
Card assigned CSN #1
Vendor ID PMC2430 (0x3024a341), Serial Number 0xffffffff
PnP Version 1.0, Vendor Version 0
Device Description: Pace 56 Voice Internal Plug & Play Modem
Logical Device ID: PMC2430 0x3024a341 #0
Device supports I/O Range Check
TAG Start DF
I/O Range 0x3f8 .. 0x3f8, alignment 0x8, len 0x8
[16-bit addr]
IRQ: 4 - only one type (true/edge)[more TAG lines elided]TAG End DF
End Tag
Successfully got 31 resources, 1 logical fdevs
-- card select # 0x0001
CSN PMC2430 (0x3024a341), Serial Number 0xffffffff
Logical device #0
IO: 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8
IRQ 5 0
DMA 4 0
IO range check 0x00 activate 0x01The information you require is in the
Vendor ID line at the start of the output. The
hexadecimal number in parentheses (0x3024a341 in this example)
is the PnP id and the string immediately before this (PMC2430)
is a unique ASCII id. This information needs adding to the file
/usr/src/sys/isa/sio.c.You should first make a backup of sio.c
just in case things go wrong. You will also need it to make the
patch to submit with your PR (you are going to submit a PR,
aren't you?) then edit sio.c and search
for the linestatic struct isa_pnp_id sio_ids[] = {then scroll down to find the correct place to add the entry
for your device. The entries look like this, and are sorted on
the ASCII Vendor ID string which should be included in the
comment to the right of the line of code along with all (if it
will fit) or part of the Device Description
from the output of &man.pnpinfo.8;:{0x0f804f3f, NULL}, /* OZO800f - Zoom 2812 (56k Modem) */
{0x39804f3f, NULL}, /* OZO8039 - Zoom 56k flex */
{0x3024a341, NULL}, /* PMC2430 - Pace 56 Voice Internal Modem */
{0x1000eb49, NULL}, /* ROK0010 - Rockwell ? */
{0x5002734a, NULL}, /* RSS0250 - 5614Jx3(G) Internal Modem */Add the hexadecimal Vendor ID for your device in the
correct place, save the file, rebuild your kernel, and reboot.
Your device should now be found as an sio
device as it was under FreeBSD 3.xWhy do I get the error nlist failed when
running, for example, top or
systat?The problem is that the application you are trying to run is
looking for a specific kernel symbol, but, for whatever reason,
cannot find it; this error stems from one of two problems:Your kernel and userland are not synchronized (i.e., you
built a new kernel but did not do an
installworld, or vice versa), and
thus the symbol table is different from what the user
application thinks it is. If this is the case, simply
complete the upgrade process (see
/usr/src/UPDATING for the correct
sequence).You are not using /boot/loader to load
your kernel, but doing it directly from boot2 (see
&man.boot.8;). While there is nothing wrong with bypassing
/boot/loader, it generally does a better
job of making the kernel symbols available to user
applications.Why does it take so long to connect to my computer via
ssh or telnet?The symptom: there is a long delay between the time the TCP
connection is established and the time when the client software
asks for a password (or, in &man.telnet.1;'s case, when a login
prompt appears).The problem: more likely than not, the delay is caused by
the server software trying to resolve the client's IP address
into a hostname. Many servers, including the Telnet and SSH
servers that come with FreeBSD, do this in order to, among
other things, store the hostname in a log file for future
reference by the administrator.The remedy: if the problem occurs whenever you connect from
your computer (the client) to any server, the problem is with
the client; likewise, if the problem only occurs when someone
connects to your computer (the server) the problem is with the
server.If the problem is with the client, the only remedy is to
fix the DNS so the server can resolve it. If this is on a
local network, consider it a server problem and keep reading;
conversely, if this is on the global Internet, you will most
likely need to contact your ISP and ask them to fix it for
you.If the problem is with the server, and this is on a local
network, you need to configure the server to be able to resolve
address-to-hostname queries for your local address range. See
the &man.hosts.5; and &man.named.8; manual pages for more
information. If this is on the global Internet, the problem
may be that your server's resolver is not functioning
correctly. To check, try to look up another host--say,
www.yahoo.com. If it does not work, that is
your problem.What does stray IRQ mean?Stray IRQs are indications of hardware IRQ glitches,
mostly from hardware that removes its interrupt request in
the middle of the interrupt request acknowledge
cycle.One has three options for dealing with this:Live with the warnings. All except the first 5
per irq are suppressed anyway.Break the warnings by changing 5 to 0 in
isa_strayintr() so that all the
warnings are suppressed.Break the warnings by installing parallel port
hardware that uses irq 7 and the ppp driver for it (this
happens on most systems), and install an ide drive or
other hardware that uses irq 15 and a suitable driver
for it.Why does file: table is full show up
repeatedly in dmesg?
This error is caused when you have exhausted the number of
available file descriptors on your system. The file table in
memory is full.
The solution:
Manually adjust the kern.maxfiles kernel limit
setting.
&prompt.root; sysctl -w kern.maxfiles=nAdjust n according to your system needs.
Each open file, socket, or fifo uses one file descriptor.
A large-scale server may easily require tens of thousands of
file descriptors (10,000+), depending on the kind and number
of services running concurrently.The number of default file descriptors set in the kernel is
dictated by themaxusers 32maxusers line in your kernel
config file. Increasing this will proportionally increase
kern.maxfiles.
You can see what kern.maxfiles is
currently set to by:
&prompt.root; sysctl kern.maxfiles
kern.maxfiles: 1064Why does the clock on my laptop keep incorrect time?Your laptop has two or more clocks, and FreeBSD has chosen to
use the wrong one.Run &man.dmesg.8;, and check for lines that contain
Timecounter. The last line printed is the one
that FreeBSD chose, and will almost certainly be
TSC.&prompt.root; dmesg | grep Timecounter
Timecounter "i8254" frequency 1193182 Hz
Timecounter "TSC" frequency 595573479 HzYou can confirm this by checking the
kern.timecounter.hardware
&man.sysctl.3;.&prompt.root; sysctl kern.timecounter.hardware
kern.timecounter.hardware: TSCThe BIOS may modify the TSC clock—perhaps to change the
speed of the processor when running from batteries, or going in to
a power saving mode, but FreeBSD is unaware of these adjustments,
and appears to gain or lose time.In this example, the i8254 clock is also
available, and can be selected by writing its name to the
kern.timecounter.hardware
&man.sysctl.3;.&prompt.root; sysctl -w kern.timecounter.hardware=i8254
kern.timecounter.hardware: TSC -> i8254Your laptop should now start keeping more accurate
time.To have this change automatically run at boot time, add the
following line to /etc/sysctl.conf.kern.timecounter.hardware=i8254Why does FreeBSD's boot loader display
Read error and stop after the BIOS
screen?FreeBSD's boot loader is incorrectly recognizing the hard
drive's geometry. This must be manually set within fdisk when
creating or modifying FreeBSD's slice.
The correct drive geometry values can be found within the
machine's BIOS. Look for the number of cylinders, heads and
sectors for the particular drive.
Within &man.sysinstall.8;'s fdisk, hit
G to set the drive geometry.A dialog will pop up requesting the number of cylinders, heads
and sectors. Type the numbers found from the BIOS separates by
forward slashes.
5000 cylinders, 250 sectors and 60 sectors would be entered as
5000/250/60Press enter to set the values, and hit
W to write the
new partition table to the drive.
Another operating system destroyed my Boot Manager. How do I
get it back?
Enter &man.sysinstall.8; and choose Configure,
then Fdisk. Select the disk the Boot Manager resided on
with the space key. Press
W to write changes to the drive. A prompt
will appear asking which boot loader to install. Select this,
and it will be restored.
Commercial ApplicationsThis section is still very sparse, though we are hoping, of
course, that companies will add to it! :) The FreeBSD group has
no financial interest in any of the companies listed here but
simply lists them as a public service (and feels that commercial
interest in FreeBSD can have very positive effects on FreeBSD's
long-term viability). We encourage commercial software vendors to
send their entries here for inclusion. See the
+ URL="../../../../commercial/index.html">the
Vendors page for a longer list.Where can I get an Office Suite for FreeBSD?
- The FreeBSD Mall
+ The FreeBSD Mall
offers a FreeBSD native version of VistaSource
+ url="http://www.vistasource.com/">VistaSource
ApplixWare 5.ApplixWare is a rich full-featured, commercial
Office Suite for FreeBSD containing a word processor,
spreadsheet, presentation program, vector drawing
package, and other applications.
You can purchase ApplixWare for FreeBSD here.
The Linux version of StarOffice
+ url="http://www.sun.com/staroffice/">StarOffice
works flawlessly on FreeBSD. The easiest way to
install the Linux version of StarOffice is through the
FreeBSD
Ports collection. Future versions of the
open-source OpenOffice
+ url="http://www.openoffice.org/">OpenOffice
suite should work as well.Where can I get Motif for FreeBSD?The Open Group has released the source code to Motif 2.1.30.
You can install the open-motif package, or
compile it from ports. Refer to
the ports section of the
Handbook for more information on how to do this.
The Open Motif distribution only allows redistribution
- if it is running on an
+ if it is running on an
open source operating system.In addition, there are commercial distributions of the Motif
software available. These, however, are not for free, but their
license allows them to be used in closed-source software.
Contact Apps2go for the
least expensive ELF Motif 2.1.20 distribution for FreeBSD
(either i386 or Alpha).There are two distributions, the developement
edition and the runtime edition (for
much less). These distributions includes:OSF/Motif manager, xmbind, panner, wsm.Development kit with uil, mrm, xm, xmcxx, include
and Imake files.Static and dynamic ELF libraries (for use with
FreeBSD 3.0 and above).Demonstration applets.Be sure to specify that you want the FreeBSD version of
Motif when ordering (do not forget to mention the architecture
you want too)! Versions for NetBSD and OpenBSD are also sold by
Apps2go. This is currently a FTP only
download.More info
Apps2go WWW pageorsales@apps2go.com or
support@apps2go.comorphone (817) 431 8775 or +1 817 431-8775Contact Metro Link
for an either ELF or a.out Motif 2.1 distribution for
FreeBSD.This distribution includes:OSF/Motif manager, xmbind, panner, wsm.Development kit with uil, mrm, xm, xmcxx, include
and Imake files.Static and dynamic libraries (specify ELF for use
with FreeBSD 3.0 and later; or a.out for use with FreeBSD
2.2.8 and earlier).Demonstration applets.Preformatted man pages.Be sure to specify that you want the FreeBSD version
of Motif when ordering! Versions for Linux are also sold by
Metro Link. This is available on either a
CDROM or for FTP download.Contact Xi Graphics for an
a.out Motif 2.0 distribution for FreeBSD.This distribution includes:OSF/Motif manager, xmbind, panner, wsm.Development kit with uil, mrm, xm, xmcxx, include
and Imake files.Static and dynamic libraries (for use with FreeBSD
2.2.8 and earlier).Demonstration applets.Preformatted man pages.Be sure to specify that you want the FreeBSD version
of Motif when ordering! Versions for BSDI and Linux are also
sold by Xi Graphics. This is currently a 4
diskette set... in the future this will change to a unified CD
distribution like their CDE.Where can I get CDE for FreeBSD?Xi Graphics used to sell CDE
for FreeBSD, but no longer do.KDE is an open
source X11 desktop which is similar to CDE in many respects.
You might also like the look and feel of xfce. KDE and xfce are both
- in the ports
+ in the ports
system.Are there any commercial high-performance X servers?Yes, Xi Graphics
and Metro Link
sell Accelerated-X product for FreeBSD and other Intel based
systems.The Metro Link offering is a high performance X Server
that offers easy configuration using the FreeBSD Package suite
of tools, support for multiple concurrent video boards and is
distributed in binary form only, in a convenient FTP download.
Not to mention the Metro Link offering is available at the very
reasonable price of $39. Metro Link also sells both ELF and a.out Motif for
FreeBSD (see above).More info
Metro Link WWW pageorsales@metrolink.com
or tech@metrolink.comorphone (954) 938-0283 or +1 954 938-0283The Xi Graphics offering is a high performance X Server
that offers easy configuration, support for multiple concurrent
video boards and is distributed in binary form only, in a
unified diskette distribution for FreeBSD and Linux. Xi
Graphics also offers a high performance X Server tailored for
laptop support.There is a free compatibility demo of
version 5.0 available.Xi Graphics also sells Motif and CDE for FreeBSD (see
above).More info
Xi Graphics WWW pageorsales@xig.com
or support@xig.comorphone (800) 946 7433 or +1 303 298-7478.Are there any Database systems for FreeBSD?Yes! See the
+ URL="../../../../commercial/software_bycat.html#CATEGORY_DATABASE">
Commercial Vendors section of FreeBSD's Web site.Also see the
+ URL="../../../../ports/databases.html">
Databases section of the Ports collection.Can I run Oracle on FreeBSD?Yes. The following pages tell you exactly how to setup
Linux-Oracle on FreeBSD:
http://www.scc.nl/~marcel/howto-oracle.html
http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsdUser ApplicationsSo, where are all the user applications?Please take a look at
- the ports
+ the ports
page for info on software packages ported to FreeBSD.
The list currently tops 3400 and is growing daily, so come back
to check often or subscribe to the
freebsd-announce mailing list for periodic updates on
new entries.Most ports should be available for the 2.2, 3.x and 4.x
branches, and many of them should work on 2.1.x systems as
well. Each time a FreeBSD release is made, a snapshot of the
ports tree at the time of release in also included in the
ports/ directory.We also support the concept of a package,
essentially no more than a gzipped binary distribution with a
little extra intelligence embedded in it for doing whatever
custom installation work is required. A package can be
installed and uninstalled again easily without having to know
the gory details of which files it includes.Use the package installation menu in
/stand/sysinstall (under the
post-configuration menu item) or invoke the
&man.pkg.add.1; command on the specific package
files you are interested in installing. Package files can
usually be identified by their .tgz suffix
and CDROM distribution people will have a
packages/All directory on their CD which
contains such files. They can also be downloaded over the net
for various versions of FreeBSD at the following
locations:for 2.2.8-RELEASE/2.2.8-STABLE
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-2.2.8/for 3.X-RELEASE/3.X-STABLE
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-3-stable/for 4.X-RELEASE/4-STABLE
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/for 5.X-CURRENT
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-currentor your nearest local mirror site.Note that all ports may not be available as packages since
new ones are constantly being added. It is always a good idea
to check back periodically to see which packages are available
at the ftp.FreeBSD.org
master site.Where do I find libc.so.3.0?You are trying to run a package built on 2.2 and later on
a 2.1.x system. Please take a look at the previous section and
get the correct port/package for your system.Why do I get a message reading Error: can't find
libc.so.4.0?You accidently downloaded packages meant for 4.X and 5.X
systems and attempted to install them on your 2.X or 3.X
FreeBSD system. Please download the correct version of the
packages.Why does ghostscript give lots of errors with my
386/486SX?You do not have a math co-processor, right?
You will need to add the alternative math emulator to your
kernel; you do this by adding the following to your kernel
config file and it will be compiled in.options GPL_MATH_EMULATEYou will need to remove the
MATH_EMULATE option when you do
this.Why do SCO/iBCS2 applications bomb on
socksys? (FreeBSD 3.0 and older only).You first need to edit the
/etc/sysconfig (or
/etc/rc.conf, see &man.rc.conf.5;) file in the last section to change the
following variable to YES:# Set to YES if you want ibcs2 (SCO) emulation loaded at startup
ibcs2=NOIt will load the ibcs2 kernel module at startup.You will then need to set up /compat/ibcs2/dev to look
like:lrwxr-xr-x 1 root wheel 9 Oct 15 22:20 X0R@ -> /dev/null
lrwxr-xr-x 1 root wheel 7 Oct 15 22:20 nfsd@ -> socksys
-rw-rw-r-- 1 root wheel 0 Oct 28 12:02 null
lrwxr-xr-x 1 root wheel 9 Oct 15 22:20 socksys@ -> /dev/null
crw-rw-rw- 1 root wheel 41, 1 Oct 15 22:14 spxYou just need socksys to go to
/dev/null (see &man.null.4;)
to fake the open & close. The code in -CURRENT will handle
the rest. This is much cleaner than the way it was done before.
If you want the spx driver for a local
socket X connection, define SPX_HACK when
you compile the system.How do I configure INN (Internet News) for my machine?After installing the inn package or port, an excellent
place to start is Dave Barr's
INN Page where you will find the INN FAQ.What version of Microsoft FrontPage should I get?Use the Port, Luke! A pre-patched version of Apache is
available in the ports tree.Does FreeBSD support Java?Yes. Please see
+ URL="../../../../java/index.html">
http://www.FreeBSD.org/java/.Why can't I build this port on my 3.X-STABLE machine?If you are running a FreeBSD version that lags
significantly behind -CURRENT or -STABLE, you may need a ports
- upgrade kit from
+ upgrade kit from
http://www.FreeBSD.org/ports/. If you are up to date,
then someone might have committed a change to the port which
works for -CURRENT but which broke the port for -STABLE. Please
submit a bug report on this with the
&man.send-pr.1; command, since the ports
collection is supposed to work for both the -CURRENT and
-STABLE branches.Where do I find ld.so?If you want to run some a.out applications like
Netscape Navigator on an Elf'ened machine such as 3.1-R or
later, it would need /usr/libexec/ld.so
and some a.out libs. They are included in the compat22
distribution. Use /stand/sysinstall or
install.sh in the compat22 subdirectory
and install it. Also read ERRATAs for 3.1-R and 3.2-R.I updated the sources, now how do I update my installed
ports?Unfortunately, there is no easy way to update installed
ports. The &man.pkg.version.1; command can be used
to generate a script that will update the installed ports with
a newer version in the ports tree:&prompt.root; pkg_version > /tmp/myscriptThe output script must be edited by
hand before you use it. Current versions of
&man.pkg.version.1; force this by inserting an
&man.exit.1; at the beginning of the script.You should save the output of the script, as it will note
packages that depend on the one that has been updated. These
may or may not need to be updated as well. The usual case where
they need to be updated is that a shared library has changed
version numbers, so the ports that used that library need to be
rebuilt to use the new version.If your system is up full time, the &man.periodic.8 system
can be used to generate a weekly list of ports that might need
updating by setting
weekly_status_pkg_enable="YES" in
/etc/periodic.conf.Why is /bin/sh so minimal? Why doesn't
FreeBSD use bash or another shell?Because POSIX says that there shall be such a shell.The more complicated answer: many people need to write shell
scripts which will be portable across many systems. That is why
POSIX specifies the shell and utility commands in great detail.
Most scripts are written in Bourne shell, and because several
important programming interfaces (&man.make.1;, &man.system.3;,
&man.popen.3;, and analogues in higher-level scripting
languages like Perl and Tcl) are specified to use the Bourne
shell to interpret commands. Because the Bourne shell is so
often and widely used, it is important for it to be quick to
start, be deterministic in its behavior, and have a small
memory footprint.The existing implementation is our best effort at meeting as
many of these requirements simultaneously as we can. In order to
keep /bin/sh small, we have not provided many
of the convenience features that other shells have. That is why the
Ports Collection includes more featureful shells like bash, scsh,
tcsh, and zsh. (You can compare for yourself the memory
utilization of all these shells by looking at the
VSZ and RSS columns in a ps
-u listing.)Kernel ConfigurationI would like to customize my kernel. Is it difficult?Not at all! Check out the
kernel config section of the Handbook.It is recommended that you make a dated snapshot
of your kernel
in kernel.YYMMDD after you get it all
working, that way if you do something dire the next time
you play with your configuration you can boot that kernel
instead of having to go all the way back to
kernel.GENERIC. This is particularly
important if you are now booting off a controller that is not
supported in the GENERIC kernel.My kernel compiles fail because
_hw_float is missing. How do I solve
this problem?Let me guess. You removed
npx0 (see &man.npx.4;)
from your kernel configuration file because you do not have a
math co-processor, right? Wrong! :-) The
npx0 is
MANDATORY. Even if you do not have a
mathematic co-processor, you must
include the npx0 device.Why is my kernel so big (over 10MB)?Chances are, you compiled your kernel in
debug mode. Kernels built in debug
mode contain many symbols that are used for debugging, thus
greatly increasing the size of the kernel. Note that if you
running a FreeBSD 3.0 or later system, there will be little
or no performance decrease from running a debug kernel,
and it is useful to keep one around in case of a system
panic.However, if you are running low on disk space, or
you simply do not want to run a debug kernel, make sure
that both of the following are true:You do not have a line in your kernel
configuration file that reads:makeoptions DEBUG=-gYou are not running &man.config.8; with
the option.Both of the above situations will cause your kernel to
be built in debug mode. As long as you make sure you follow
the steps above, you can build your kernel normally, and you
should notice a fairly large size decrease; most kernels
tend to be around 1.5MB to 2MB.Why do I get interrupt conflicts with multi-port serial
code?When I compile a kernel
with multi-port serial code, it tells me that only the first
port is probed and the rest skipped due to interrupt conflicts.
How do I fix this?The problem here is that
FreeBSD has code built-in to keep the kernel from getting
trashed due to hardware or software conflicts. The way to fix
this is to leave out the IRQ settings on all but one port. Here
is a example:#
# Multiport high-speed serial line - 16550 UARTS
#
device sio2 at isa? port 0x2a0 tty irq 5 flags 0x501 vector siointr
device sio3 at isa? port 0x2a8 tty flags 0x501 vector siointr
device sio4 at isa? port 0x2b0 tty flags 0x501 vector siointr
device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointrWhy does every kernel I try to build fail to compile, even
GENERIC?There are a number of possible causes for this problem.
They are, in no particular order:You are not using the new make
buildkernel and make
installkernel targets, and your source tree is
different from the one used to build the currently running
system (e.g., you are compiling 4.3-RELEASE on a 4.0-RELEASE
system). If you are attempting an upgrade, please read the
/usr/src/UPDATING file, paying
particular attention to the COMMON ITEMS
section at the end.You are using the new make
buildkernel and make
installkernel targets, but you failed to assert
the completion of the make buildworld
target. The make buildkernel target
relies on files generated by the make
buildworld target to complete its job
correctly.Even if you are trying to build FreeBSD-STABLE, it is possible that
you fetched the source tree at a time when it was either
being modified, or broken for other reasons; only releases
are absolutely guaranteed to be buildable, although FreeBSD-STABLE builds fine the
majority of the time. If you have not already done so, try
re-fetching the source tree and see if the problem goes
away. Try using a different server in case the one you are
using is having problems.System AdministrationWhere are the system start-up configuration files?From 2.0.5R to 2.2.1R, the primary configuration file is
/etc/sysconfig. All the options are to be
specified in this file and other files such as
/etc/rc (see &man.rc.8;)
and /etc/netstart just include it.Look in the /etc/sysconfig file and
change the value to match your system. This file is filled with
comments to show what to put in there.In post-2.2.1 and 3.0, /etc/sysconfig
was renamed to a more self-describing &man.rc.conf.5;
file and the syntax cleaned up a bit in the process.
/etc/netstart was also renamed to
/etc/rc.network so that all files could be
copied with a
cp
/usr/src/etc/rc* /etc command.And, in 3.1 and later, /etc/rc.conf
has been moved to /etc/defaults/rc.conf.
Do not edit this file! Instead, if there
is any entry in /etc/defaults/rc.conf that
you want to change, you should copy the line into
/etc/rc.conf and change it there.For example, if you wish to start named, the DNS server
included with FreeBSD in FreeBSD 3.1 or later, all you need to
do is:&prompt.root; echo named_enable="YES" >> /etc/rc.confTo start up local services in FreeBSD 3.1 or later, place
shell scripts in the /usr/local/etc/rc.d
directory. These shell scripts should be set executable, and
end with a .sh. In FreeBSD 3.0 and earlier releases, you should
edit the /etc/rc.local file.The /etc/rc.serial is for serial port
initialization (e.g. locking the port characteristics, and so
on.).The /etc/rc.i386 is for Intel-specifics
settings, such as iBCS2 emulation or the PC system console
configuration.How do I add a user easily?Use the &man.adduser.8;
command. For more complicated usage, the &man.pw.8;
command.To remove the user again, use the &man.rmuser.8;
command. Once again, &man.pw.8; will work as
well.How can I add my new hard disk to my FreeBSD system?See the Disk Formatting Tutorial at
+ URL="../../articles/formatting-media/index.html">
www.FreeBSD.org.I have a new removable drive, how do I use it?Whether it is a removable drive like a ZIP or an EZ drive
(or even a floppy, if you want to use it that way), or a new
hard disk, once it is installed and recognized by the system,
and you have your cartridge/floppy/whatever slotted in, things
are pretty much the same for all devices.(this section is based on
Mark Mayo's ZIP FAQ)If it is a ZIP drive or a floppy , you have already got a DOS
filesystem on it, you can use a command like this:&prompt.root; mount -t msdos /dev/fd0c /floppyif it is a floppy, or this:&prompt.root; mount -t msdos /dev/da2s4 /zipfor a ZIP disk with the factory configuration.For other disks, see how they are laid out using
&man.fdisk.8; or
&man.sysinstall.8;.The rest of the examples will be for a ZIP drive on da2,
the third SCSI disk.Unless it is a floppy, or a removable you plan on sharing
with other people, it is probably a better idea to stick a BSD
file system on it. You will get long filename support, at least a
2X improvement in performance, and a lot more stability. First,
you need to redo the DOS-level partitions/filesystems. You can
either use &man.fdisk.8; or
/stand/sysinstall, or for a small drive
that you do not want to bother with multiple operating system
support on, just blow away the whole FAT partition table
(slices) and just use the BSD partitioning:&prompt.root; dd if=/dev/zero of=/dev/rda2 count=2
&prompt.root; disklabel -Brw da2 autoYou can use disklabel or
/stand/sysinstall to create multiple BSD
partitions. You will certainly want to do this if you are adding
swap space on a fixed disk, but it is probably irrelevant on a
removable drive like a ZIP.Finally, create a new file system, this one is on our ZIP
drive using the whole disk:&prompt.root; newfs /dev/rda2cand mount it:&prompt.root; mount /dev/da2c /zipand it is probably a good idea to add a line like this to
/etc/fstab (see &man.fstab.5;) so you can just type
mount /zip in the future:/dev/da2c /zip ffs rw,noauto 0 0Why do I keep getting messages like root: not
found after editing my crontab file?This is normally caused by editing the system crontab
(/etc/crontab) and then using
&man.crontab.1; to install it:&prompt.root; crontab /etc/crontabThis is not the correct way to do things. The system
crontab has a different format to the per-user crontabs
which &man.crontab.1; updates (the &man.crontab.5; manual
page explains the differences in more detail).If this is what you did, the extra crontab is simply a
copy of /etc/crontab in the wrong
format it. Delete it with the command:&prompt.root; crontab -rNext time, when you edit
/etc/crontab, you should not do
anything to inform &man.cron.8; of the changes, since it
will notice them automatically.If you want something to be run once per day, week, or
month, it is probably better to add shell scripts
/usr/local/etc/periodic, and let the
&man.periodic.8; command run from the system cron schedule
it with the other periodic system tasks.The actual reason for the error is that the system
crontab has an extra field, specifying which user to run the
command as. In the default system crontab provided with
FreeBSD, this is root for all entries.
When this crontab is used as the root
user's crontab (which is not the
same as the system crontab), &man.cron.8; assumes the string
root is the first word of the command to
execute, but no such command exists.Why do I get the error, you are not in the correct
group to su root when I try to su to root?This is a security feature. In order to su to
root (or any other account with superuser
privileges), you must be in the wheel
group. If this feature were not there, anybody with an account
on a system who also found out root's
password would be able to gain superuser level access to the
system. With this feature, this is not strictly true;
&man.su.1; will prevent them from even trying to enter the
password if they are not in wheel.To allow someone to su to root, simply
put them in the wheel group.I made a mistake in rc.conf,
or another startup file, and
now I cannot edit it because the filesystem is read-only.
What should I do?When you get the prompt to enter the shell
pathname, simply press ENTER, and run
mount / to re-mount the root filesystem in
read/write mode. You may also need to run mount -a -t
ufs to mount the filesystem where your favourite
editor is defined. If your favourite editor is on a network
filesystem, you will need to either configure the network
manually before you can mount network filesystems, or use an
editor which resides on a local filesystem, such as
&man.ed.1;.If you intend to use a full screen editor such
as &man.vi.1; or &man.emacs.1;, you may also need to
run export TERM=cons25 so that these
editors can load the correct data from the &man.termcap.5;
database.Once you have performed these steps, you can edit
/etc/rc.conf as you usually would
to fix the syntax error. The error message displayed
immediately after the kernel boot messages should tell you
the number of the line in the file which is at fault.How do I mount a secondary DOS partition?The secondary DOS partitions are found after ALL the primary
partitions. For example, if you have an E
partition as the second DOS partition on the second SCSI drive,
you need to create the special files for slice 5
in /dev, then mount /dev/da1s5:&prompt.root; cd /dev
&prompt.root; sh MAKEDEV da1s5
&prompt.root; mount -t msdos /dev/da1s5 /dos/eCan I mount other foreign filesystems under FreeBSD?Digital UNIXUFS CDROMs can be mounted directly on FreeBSD.
Mounting disk partitions from Digital UNIX and other
systems that support UFS may be more complex, depending
on the details of the disk partitioning for the operating
system in question.LinuxAs of 2.2, FreeBSD supports ext2fs
partitions. See &man.mount.ext2fs.8; for more
information.NTA read-only NTFS driver exists for FreeBSD. For more
information, see this tutorial by Mark Ovens at
- http://ukug.uk.freebsd.org/~mark/ntfs_install.html.
+ URL="http://ukug.uk.FreeBSD.org/~mark/ntfs_install.html">
+ http://ukug.uk.FreeBSD.org/~mark/ntfs_install.html.
Any other information on this subject would be
appreciated.How can I use the NT loader to boot FreeBSD?This procedure is slightly different for 2.2.x and 3.x
(with the 3-stage boot) systems.The general idea is that you copy the first sector of your
native root FreeBSD partition into a file in the DOS/NT
partition. Assuming you name that file something like
c:\bootsect.bsd (inspired by
c:\bootsect.dos), you can then edit the
c:\boot.ini file to come up with something
like this:[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT"
C:\BOOTSECT.BSD="FreeBSD"
C:\="DOS"For 2.2.x systems this procedure assumes that DOS, NT,
FreeBSD, or whatever have been installed into their respective
fdisk partitions on the same
disk. This example was tested on a system where DOS & NT
were on the first fdisk partition, and FreeBSD on the second.
FreeBSD was also set up to boot from its native partition, not
the disk's MBR.Mount a DOS-formatted floppy (if you have converted to NTFS)
or the FAT partition, under, say,
/mnt.&prompt.root; dd if=/dev/rda0a of=/mnt/bootsect.bsd bs=512 count=1Reboot into DOS or NT. NTFS users copy the
bootsect.bsd and/or the
bootsect.lnx file from the floppy to
C:\. Modify the attributes (permissions)
on boot.ini with:C:\>attrib -s -r c:\boot.iniEdit to add the appropriate entries from the example
boot.ini above, and restore the
attributes:C:\>attrib +s +r c:\boot.iniIf FreeBSD is booting from the MBR, restore it with the DOS
fdisk command after you reconfigure them to
boot from their native partitions.For FreeBSD 3.x systems the procedure is somewhat
simpler.If FreeBSD is installed on the same disk as the NT boot
partition simply copy /boot/boot1 to
C:\BOOTSECT.BSD However, if FreeBSD is
installed on a different disk /boot/boot1
will not work, /boot/boot0 is needed.
DO NOT SIMPLY COPY /boot/boot0
INSTEAD OF /boot/boot1, YOU WILL
OVERWRITE YOUR PARTITION TABLE AND RENDER YOUR COMPUTER
UN-BOOTABLE!/boot/boot0 needs to be installed using
sysinstall by selecting the FreeBSD boot manager on the
screen which asks if you wish to use a boot manager. This is
because /boot/boot0 has the partition
table area filled with NULL characters but sysinstall copies
the partition table before copying
/boot/boot0 to the MBR.When the FreeBSD boot manager runs it records the last
OS booted by setting the active flag on the partition table
entry for that OS and then writes the whole 512-bytes of itself
back to the MBR so if you just copy
/boot/boot0 to
C:\BOOTSECT.BSD then it writes an empty
partition table, with the active flag set on one entry, to the
MBR.How do I boot FreeBSD and Linux from LILO?If you have FreeBSD and Linux on the same disk, just follow
LILO's installation instructions for booting a non-Linux
operating system. Very briefly, these are:Boot Linux, and add the following lines to
/etc/lilo.conf:other=/dev/hda2
table=/dev/hda
label=FreeBSD(the above assumes that your FreeBSD slice is known to Linux
as /dev/hda2; tailor to suit your setup).
Then, run lilo as root and you should be
done.If FreeBSD resides on another disk, you need to add
loader=/boot/chain.b to the LILO entry.
For example:other=/dev/dab4
table=/dev/dab
loader=/boot/chain.b
label=FreeBSDIn some cases you may need to specify the BIOS drive number
to the FreeBSD boot loader to successfully boot off the second
disk. For example, if your FreeBSD SCSI disk is probed by BIOS
as BIOS disk 1, at the FreeBSD boot loader prompt you need to
specify:Boot: 1:da(0,a)/kernelOn FreeBSD 2.2.5 and later, you can configure
&man.boot.8;
to automatically do this for you at boot time.The
Linux+FreeBSD mini-HOWTO is a good reference for
FreeBSD and Linux interoperability issues.How do I boot FreeBSD and Linux using BootEasy?Install LILO at the start of your Linux boot partition
instead of in the Master Boot Record. You can then boot LILO
from BootEasy.If you are running Windows-95 and Linux this is recommended
anyway, to make it simpler to get Linux booting again if you
should need to reinstall Windows95 (which is a Jealous
Operating System, and will bear no other Operating Systems in
the Master Boot Record).Will a dangerously dedicated disk endanger
my health?The installation procedure allows
you to chose two different methods in partitioning your
harddisk(s). The default way makes it compatible with other
operating systems on the same machine, by using fdisk table
entries (called slices in FreeBSD), with a
FreeBSD slice that employs partitions of its own. Optionally,
one can chose to install a boot-selector to switch between the
possible operating systems on the disk(s). The alternative uses
the entire disk for FreeBSD, and makes no attempt to be
compatible with other operating systems.So why it is called dangerous? A disk in
this mode does not contain what normal PC utilities would
consider a valid fdisk table. Depending on how well they have
been designed, they might complain at you once they are getting
in contact with such a disk, or even worse, they might damage
the BSD bootstrap without even asking or notifying you. In
addition, the dangerously dedicated disk's
layout is known to confuse many BIOSsen, including those from
AWARD (eg. as found in HP Netserver and Micronics systems as
well as many others) and Symbios/NCR (for the popular 53C8xx
range of SCSI controllers). This is not a complete list, there
are more. Symptoms of this confusion include the read
error message printed by the FreeBSD bootstrap when it
cannot find itself, as well as system lockups when
booting.Why have this mode at all then? It only saves a few kbytes
of disk space, and it can cause real problems for a new
installation. Dangerously dedicated mode's
origins lie in a desire to avoid one of the most common
problems plaguing new FreeBSD installers - matching the BIOS
geometry numbers for a disk to the disk
itself.Geometry is an outdated concept, but one
still at the heart of the PC's BIOS and its interaction with
disks. When the FreeBSD installer creates slices, it has to
record the location of these slices on the disk in a fashion
that corresponds with the way the BIOS expects to find them. If
it gets it wrong, you will not be able to boot.Dangerously dedicated mode tries to work
around this by making the problem simpler. In some cases, it
gets it right. But it is meant to be used as a last-ditch
alternative - there are better ways to solve the problem 99
times out of 100.So, how do you avoid the need for DD mode
when you are installing? Start by making a note of the geometry
that your BIOS claims to be using for your disks. You can
arrange to have the kernel print this as it boots by specifying
at the boot: prompt, or
using boot -v in the loader. Just before the
installer starts, the kernel will print a list of BIOS
geometries. Do not panic - wait for the installer to start and
then use scrollback to read the numbers. Typically the BIOS
disk units will be in the same order that FreeBSD lists your
disks, first IDE, then SCSI.When you are slicing up your disk, check that the disk
geometry displayed in the FDISK screen is correct (ie. it
matches the BIOS numbers); if it is wrong, use the
g key to fix it. You may have to do this if
there is absolutely nothing on the disk, or if the disk has been
moved from another system. Note that this is only an issue with
the disk that you are going to boot from; FreeBSD will sort
itself out just fine with any other disks you may have.Once you have got the BIOS and FreeBSD agreeing about the
geometry of the disk, your problems are almost guaranteed to be
over, and with no need for DD mode at all. If,
however, you are still greeted with the dreaded read
error message when you try to boot, it is time to cross
your fingers and go for it - there's nothing left to
lose.To return a dangerously dedicated disk
for normal PC use, there are basically two options. The first
is, you write enough NULL bytes over the MBR to make any
subsequent installation believe this to be a blank disk. You
can do this for example with&prompt.root; dd if=/dev/zero of=/dev/rda0 count=15Alternatively, the undocumented DOS
featureC:\>fdisk /mbrwill to install a new master boot record as well, thus
clobbering the BSD bootstrap.How can I add more swap space?The best way is to increase the size of your swap partition,
or take advantage of this convenient excuse to add another
disk. The general rule of thumb is to have around 2x the swap
space as you have main memory. However, if you have a very
small amount of main memory you may want to configure swap
beyond that. It is also a good idea to configure sufficient
swap relative to anticipated future memory upgrades so you do
not have to futz with your swap configuration later.Adding swap onto a separate disk makes things faster than
simply adding swap onto the same disk. As an example, if you
are compiling source located on one disk, and the swap is on
another disk, this is much faster than both swap and compile on
the same disk. This is true for SCSI disks specifically.When you have several disks, configuring a swap partition on
each one is usually beneficial, even if you wind up putting
swap on a work disk. Typically, each fast disk in your system
should have some swap configured. FreeBSD supports up to 4
interleaved swap devices by default. When configuring multiple
swap partitions you generally want to make them all about the
same size, but people sometimes make their primary swap
partition larger in order to accomodate a kernel core dump. Your
primary swap partition must be at least as large as main memory
in order to be able to accomodate a kernel core.IDE drives are not able to allow access to both drives on
the same channel at the same time (FreeBSD does not support mode
4, so all IDE disk I/O is programmed).
It is still suggested that you put your swap partition on a
separate driver, however: the drives are so cheap, it is not
worth worrying about.Swapping over NFS is only recommended if you do not have a
local disk to swap to. Swapping over NFS is slow and
inefficient in FreeBSD releases prior to 4.x, but reasonably
fast in releases greater or equal to 4.0. Even so, it will be
limited to the network bandwidth available and puts an
additional burden on the NFS server.Here is an example for 64Mb vn-swap
(/usr/swap0, though of course you can use
any name that you want).Make sure your kernel was built with the linepseudo-device vn 1 #Vnode driver (turns a file into a device)in your config-file. The GENERIC kernel already contains
this.create a vn-device&prompt.root; cd /dev
&prompt.root; sh MAKEDEV vn0create a swapfile (/usr/swap0)&prompt.root; dd if=/dev/zero of=/usr/swap0 bs=1024k count=64set proper permissions on (/usr/swap0)&prompt.root; chmod 0600 /usr/swap0enable the swap file in /etc/rc.confswapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.reboot the machineTo enable the swap file immediately, type&prompt.root; vnconfig -e /dev/vn0b /usr/swap0 swapWhy am I having trouble setting up my printer?Please have a look at the Handbook entry on printing. It
should cover most of your problem. See the
Handbook entry on printing.Some printers require a host-based driver to do any kind of
printing. These so-called WinPrinters are not
natively supported by FreeBSD. If your printer does not work
in DOS or Windows NT 4.0, it is probably a WinPrinter. Your
only hope of getting one of these to work is to check if the
ports/print/pnm2ppa port supports it.
From its
+ url="http://www.FreeBSD.org/cgi/url.cgi?ports/print/pnm2ppa/pkg-descr">its
package description:
This software creates output using the PPA (printer
performance architecture) protocol. This protocol is used by
some HP "Windows-only" printers, including the HP Deskjet
820C series, the HP DeskJet 720 series, and the HP DeskJet
1000 series. [...]WWW: http://pnm2ppa.sourceforge.net/
How can I correct the keyboard mappings for my system?The kbdcontrol program has an option to load a keyboard
map file. Under /usr/share/syscons/keymaps
are a number of map files. Choose the one relevant to your
system and load it.&prompt.root; kbdcontrol -l uk.isoBoth the /usr/share/syscons/keymaps
and the .kbd extension are assumed by
&man.kbdcontrol.1;.This can be configured in /etc/sysconfig
(or
&man.rc.conf.5;). See the appropriate comments in this
file.In 2.0.5R and later, everything related to text fonts,
keyboard mapping is in
/usr/share/examples/syscons.The following mappings are currently supported:Belgian ISO-8859-1Brazilian 275 keyboard Codepage 850Brazilian 275 keyboard ISO-8859-1Danish Codepage 865Danish ISO-8859-1French ISO-8859-1German Codepage 850German ISO-8859-1Italian ISO-8859-1Japanese 106Japanese 106xLatin AmericanNorwegian ISO-8859-1Polish ISO-8859-2 (programmer's)Russian Codepage 866 (alternative)Russian koi8-r (shift)Russian koi8-rSpanish ISO-8859-1Swedish Codepage 850Swedish ISO-8859-1Swiss-German ISO-8859-1United Kingdom Codepage 850United Kingdom ISO-8859-1United States of America ISO-8859-1United States of America dvorakUnited States of America dvorakxWhy do I get messages like: unknown: <PNP0303>
can't assign resources on boot?The following is an excerpt from a post to the
freebsd-current mailing list.
&a.wollman;, 24 April 2001The can't assign resources messages
indicate that the devices are legacy ISA devices for which a
non-PnP-aware driver is compiled into the kernel. These
include devices such as keyboard controllers, the
programmable interrupt controller chip, and several other
bits of standard infrastructure. The resources cannot be
assigned because there is already a driver using those
addresses.
How come I cannot get user quotas to work properly?Do not turn on quotas on /,Put the quota file on the file system that the quotas
are to be enforced on. ie:FilesystemQuota file/usr/usr/admin/quotas/home/home/admin/quotas……What is inappropriate about my ccd?The symptom of this is:&prompt.root; ccdconfig -C
ccdconfig: ioctl (CCDIOCSET): /dev/ccd0c: Inappropriate file type or formatThis usually happens when you are trying to concatenate
the c partitions, which default to type
unused. The ccd driver requires the
underlying partition type to be FS_BSDFFS. Edit the disklabel
of the disks you are trying to concatenate and change the types
of partitions to 4.2BSD.Why can't I edit the disklabel on my ccd?The symptom of this is:&prompt.root; disklabel ccd0
(it prints something sensible here, so let's try to edit it)
&prompt.root; disklabel -e ccd0
(edit, save, quit)
disklabel: ioctl DIOCWDINFO: No disk label on disk;
use "disklabel -r" to install initial labelThis is because the disklabel returned by ccd is actually
a fake one that is not really on the disk.
You can solve this problem by writing it back explicitly,
as in:&prompt.root; disklabel ccd0 > /tmp/disklabel.tmp
&prompt.root; disklabel -Rr ccd0 /tmp/disklabel.tmp
&prompt.root; disklabel -e ccd0
(this will work now)Does FreeBSD support System V IPC primitives?Yes, FreeBSD supports System V-style IPC. This includes
shared memory, messages and semaphores. You need to add the
following lines to your kernel config to enable them.options SYSVSHM # enable shared memory
options SYSVSEM # enable for semaphores
options SYSVMSG # enable for messagingIn FreeBSD 3.2 and later, these options are already
part of the GENERIC kernel, which
means they should already be compiled into your
system.Recompile and install your kernel.How do I use sendmail for mail delivery with UUCP?The sendmail configuration that ships with FreeBSD is
suited for sites that connect directly to the Internet.
Sites that wish to exchange their mail via UUCP must install
another sendmail configuration file.Tweaking /etc/sendmail.cf manually is
considered something for purists. Sendmail version 8 comes with
a new approach of generating config files via some
&man.m4.1;
preprocessing, where the actual hand-crafted configuration is
on a higher abstraction level. You should use the configuration
files under
/usr/src/usr.sbin/sendmail/cfIf you did not install your system with full sources,
the sendmail config stuff has been broken out into a separate
source distribution tarball just for you. Assuming you have got
your CDROM mounted, do:&prompt.root; cd /cdrom/src
&prompt.root; cat scontrib.?? | tar xzf - -C /usr/src contrib/sendmailDo not panic, this is only a few hundred kilobytes in size.
The file README in the
cf directory can serve as a basic
introduction to m4 configuration.For UUCP delivery, you are best advised to use the
mailertable feature. This constitutes a
database that sendmail can use to base its routing decision
upon.First, you have to create your .mc
file. The directory
/usr/src/usr.sbin/sendmail/cf/cf is the
home of these files. Look around, there are already a few
examples. Assuming you have named your file
foo.mc, all you need to do in order to
convert it into a valid sendmail.cf
is:&prompt.root; cd /usr/src/usr.sbin/sendmail/cf/cf
&prompt.root; make foo.cf
&prompt.root; cp foo.cf /etc/sendmail.cfA typical .mc file might look
like:include(`../m4/cf.m4')
VERSIONID(`Your version number')
OSTYPE(bsd4.4)
FEATURE(nodns)
FEATURE(nocanonify)
FEATURE(mailertable)
define(`UUCP_RELAY', your.uucp.relay)
define(`UUCP_MAX_SIZE', 200000)
MAILER(local)
MAILER(smtp)
MAILER(uucp)
Cw your.alias.host.name
Cw youruucpnodename.UUCPThe nodns and
nocanonify features will prevent any usage
of the DNS during mail delivery. The
UUCP_RELAY clause is needed for bizarre
reasons, do not ask. Simply put an Internet hostname there that
is able to handle .UUCP pseudo-domain addresses; most likely,
you will enter the mail relay of your ISP there.Once you have got this, you need this file called
/etc/mailertable. A typical example of
this gender again:#
# makemap hash /etc/mailertable.db < /etc/mailertable
#
horus.interface-business.de uucp-dom:horus
.interface-business.de uucp-dom:if-bus
interface-business.de uucp-dom:if-bus
.heep.sax.de smtp8:%1
horus.UUCP uucp-dom:horus
if-bus.UUCP uucp-dom:if-bus
. uucp-dom:As you can see, this is part of a real-life file. The
first three lines handle special cases where domain-addressed
mail should not be sent out to the default route, but instead
to some UUCP neighbor in order to shortcut the
delivery path. The next line handles mail to the local Ethernet
domain that can be delivered using SMTP. Finally, the UUCP
neighbors are mentioned in the .UUCP pseudo-domain notation, to
allow for a uucp-neighbor
!recipient
override of the default rules. The last line is always a single
dot, matching everything else, with UUCP delivery to a UUCP
neighbor that serves as your universal mail gateway to the
world. All of the node names behind the
uucp-dom: keyword must be valid UUCP
neighbors, as you can verify using the command
uuname.As a reminder that this file needs to be converted into a
DBM database file before being usable, the command line to
accomplish this is best placed as a comment at the top of
the mailertable. You always have to execute this command
each time you change your mailertable.Final hint: if you are uncertain whether some particular
mail routing would work, remember the
option to sendmail. It starts sendmail in address
test mode; simply enter 0,
followed by the address you wish to test for the mail routing.
The last line tells you the used internal mail agent, the
destination host this agent will be called with, and the
(possibly translated) address. Leave this mode by typing
Control-D.&prompt.user; sendmail -bt
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
>0 foo@interface-business.de
rewrite: ruleset 0 input: foo @ interface-business . de
...
rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo \
< @ interface-business . de >
>^DHow do I set up mail with a dialup connection to the
'net?If you have got a statically assigned IP number, you should
not need to adjust anything from the default. Set your host
name up as your assigned Internet name and sendmail will do
the rest.If you have got a dynamically assigned IP number and use a
dialup ppp connection to the
Internet, you will probably be given a mailbox on your ISPs
mail server. Lets assume your ISPs domain is
myISP.com, and that your user name is
user. Lets also assume you have
called your machine bsd.home and that your
ISP has told you that you may use
relay.myISP.com as a mail relay.In order to retrieve mail from your mailbox, you will need
to install a retrieval agent. Fetchmail is a good choice as it supports
many different protocols. Usually, POP3 will be provided by
your ISP. If you have chosen to use user-ppp, you can
automatically fetch your mail when a connection to the 'net is
established with the following entry in
/etc/ppp/ppp.linkup:MYADDR:
!bg su user -c fetchmailIf you are using sendmail
(as shown below) to deliver mail to non-local accounts, put
the command !bg su user -c "sendmail -q"after the above shown entry. This forces sendmail to
process your mailqueue as soon as the connection to the 'net
is established.I am assuming that you have an account for
user on
bsd.home. In the home directory of
user on
bsd.home, create a
.fetchmailrc file:poll myISP.com protocol pop3 fetchall pass MySecretNeedless to say, this file should not be readable by
anyone except user as it contains
the password MySecret.In order to send mail with the correct
from: header, you must tell
sendmail to use user@myISP.com rather than
user@bsd.home. You may also wish to tell
sendmail to send all mail via
relay.myISP.com, allowing quicker mail
transmission.The following .mc file should
suffice:VERSIONID(`bsd.home.mc version 1.0')
OSTYPE(bsd4.4)dnl
FEATURE(nouucp)dnl
MAILER(local)dnl
MAILER(smtp)dnl
Cwlocalhost
Cwbsd.home
MASQUERADE_AS(`myISP.com')dnl
FEATURE(allmasquerade)dnl
FEATURE(masquerade_envelope)dnl
FEATURE(nocanonify)dnl
FEATURE(nodns)dnl
define(`SMART_HOST', `relay.myISP.com')
Dmbsd.home
define(`confDOMAIN_NAME',`bsd.home')dnl
define(`confDELIVERY_MODE',`deferred')dnlRefer to the previous section for details of how to turn
this .mc file into a
sendmail.cf file. Also, don't forget to
restart sendmail after updating sendmail.cf.What is this UID 0 toor account? Have I
been compromised?Do not worry. toor is an
alternative superuser account (toor is root
spelt backwards). Previously it was created when the
&man.bash.1; shell was installed but now it is created by
default. It is intended to be used with a non-standard shell so
you do not have to change root's default
shell. This is important as shells which are not part of the
base distribution (for example a shell installed from ports or
packages) are likely be to be installed in
/usr/local/bin which, by default, resides
on a different filesystem. If root's shell
is located in /usr/local/bin and
/usr (or whatever filesystem contains
/usr/local/bin) is not mounted for some
reason, root will not be able to log in to
fix a problem (although if you reboot into single user mode
you will be prompted for the path to a shell).Some people use toor for
day-to-day root tasks with a non-standard shell, leaving
root, with a standard shell, for
single user mode or emergencies. By default you cannot log
in using toor as it does not have a
password, so log in as root and set a password for
toor if you want to use it.I have forgotten the root password! What do I do?Do not Panic! Simply restart the system, type
boot -s at the Boot: prompt (just
-s for FreeBSD releases before 3.2) to
enter Single User mode. At the question about the shell to use,
hit ENTER. You will be dropped to a &prompt.root; prompt. Enter
mount -u / to remount your root filesystem
read/write, then run mount -a to remount all
the filesystems. Run passwd root to change
the root password then run &man.exit.1; to continue
booting.How do I keep Control-Alt-Delete from rebooting the
system?If you are using syscons (the default console driver)
in FreeBSD 2.2.7-RELEASE or later,
build and install a new kernel with the lineoptions SC_DISABLE_REBOOTin the configuration file. If you use the PCVT console
driver in FreeBSD 2.2.5-RELEASE or later, use the following
kernel configuration line instead:options PCVT_CTRL_ALT_DELFor older versions of FreeBSD, edit the keymap you are
using for the console and replace the boot
keywords with nop. The default keymap is
/usr/share/syscons/keymaps/us.iso.kbd. You
may have to instruct /etc/rc.conf to load
this keymap explicitly for the change to take effect. Of course
if you are using an alternate keymap for your country, you
should edit that one instead.How do I reformat DOS text files to Unix ones?Simply use this perl command:&prompt.user; perl -i.bak -npe 's/\r\n/\n/g' file ...file is the file(s) to process. The modification is done
in-place, with the original file stored with a .bak
extension.Alternatively you can use the
&man.tr.1;
command:&prompt.user; tr -d '\r' < dos-text-file > unix-filedos-text-file is the file
containing DOS text while unix-file
will contain the converted output. This can be quite a bit
faster than using perl.How do I kill processes by name?Use &man.killall.1;.Why is su bugging me about not being in
root's ACL?The error comes from the Kerberos distributed
authentication system. The problem is not fatal but annoying.
You can either run su with the -K option, or uninstall
Kerberos as described in the next question.How do I uninstall Kerberos?To remove Kerberos from the system, reinstall the bin
distribution for the release you are running. If you have
the CDROM, you can mount the cd (we will assume on /cdrom)
and run&prompt.root; cd /cdrom/bin
&prompt.root; ./install.shAlternately, you can remove all "MAKE_KERBEROS"
options from /etc/make.conf and rebuild
world.How do I add pseudoterminals to the system?If you have lots of telnet, ssh, X, or screen users,
you will probably run out of pseudoterminals. Here is how to
add more:Build and install a new kernel with the linepseudo-device pty 256in the configuration file.Run the commands&prompt.root; cd /dev
&prompt.root; sh MAKEDEV pty{1,2,3,4,5,6,7}to make 256 device nodes for the new terminals.Edit /etc/ttys and add lines
for each of the 256 terminals. They should match the form
of the existing entries, i.e. they look likettyqc none networkThe order of the letter designations is
tty[pqrsPQRS][0-9a-v], using a
regular expression. Reboot the system with the new kernel and you are
ready to go.How come I cannot create the snd0 device?There is no snd device. The name
is used as a shorthand for the various devices that make up the
FreeBSD sound driver, such as mixer,
sequencer, and
dsp.To create these devices you should&prompt.root; cd /dev
&prompt.root; sh MAKEDEV snd0How do I re-read /etc/rc.conf and re-start /etc/rc without
a reboot?Go into single user mode and then back to multi user
mode.On the console do:&prompt.root; shutdown now
(Note: without -r or -h)
&prompt.root; return
&prompt.root; exitWhat is a sandbox?Sandbox is a security term. It can mean
two things:A process which is placed inside a set of virtual
walls that are designed to prevent someone who breaks
into the process from being able to break into the wider
system.The process is said to be able to
play inside the walls. That is,
nothing the process does in regards to executing code is
supposed to be able to breech the walls so you do not
have to do a detailed audit of its code to be able to
say certain things about its security.The walls might be a userid, for example. This is
the definition used in the security and named man
pages.Take the ntalk service, for
example (see /etc/inetd.conf). This service used to run
as userid root. Now it runs as userid tty. The tty user
is a sandbox designed to make it more difficult for
someone who has successfully hacked into the system via
ntalk from being able to hack beyond that user id.A process which is placed inside a simulation of the
machine. This is more hard-core. Basically it means that
someone who is able to break into the process may believe
that he can break into the wider machine but is, in fact,
only breaking into a simulation of that machine and not
modifying any real data.The most common way to accomplish this is to build a
simulated environment in a subdirectory and then run the
processes in that directory chroot'd (i.e.
/ for that process is this
directory, not the real / of the
system).Another common use is to mount an underlying
filesystem read-only and then create a filesystem layer
on top of it that gives a process a seemingly writeable
view into that filesystem. The process may believe it is
able to write to those files, but only the process sees
the effects - other processes in the system do not,
necessarily.An attempt is made to make this sort of sandbox so
transparent that the user (or hacker) does not realize
that he is sitting in it.Unix implements two core sandboxes. One is at the
process level, and one is at the userid level.Every Unix process is completely firewalled off from every
other Unix process. One process cannot modify the address
space of another. This is unlike Windows where a process
can easily overwrite the address space of any other, leading
to a crash.A Unix process is owned by a particular userid. If the
userid is not the root user, it serves to firewall the process
off from processes owned by other users. The userid is also
used to firewall off on-disk data.What is securelevel?The securelevel is a security mechanism implemented in the
kernel. Basically, when the securelevel is positive, the
kernel restricts certain tasks; not even the superuser (i.e.,
root) is allowed to do them. At the time
of this writing, the securelevel mechanism is capable of, among
other things, limiting the ability to,unset certain file flags, such as
schg (the system immutable flag),write to kernel memory via
/dev/mem and
/dev/kmem,load kernel modules, andalter &man.ipfirewall.4; rules.To check the status of the securelevel on a running system,
simply execute the following command:&prompt.root; sysctl kern.securelevelThe output will contain the name of the &man.sysctl.8;
variable (in this case, kern.securelevel)
and a number. The latter is the current value of the
securelevel. If it is positive (i.e., greater than 0), at
least some of the securelevel's protections are enabled.You cannot lower the securelevel of a running system; being
able to do that would defeat its purpose. If you need to do a
task that requires that the securelevel be non-positive (e.g.,
an installworld or changing the date),
you will have to change the securelevel setting in
/etc/rc.conf (you want to look for the
kern_securelevel and
kern_securelevel_enable variables) and
reboot.For more information on securelevel and the specific things
all the levels do, please consult the &man.init.8; manual
page.Securelevel is not a silver bullet; it has many known
deficiencies. More often than not, it provides a false
sense of security.One of its biggest problems is that in order for it to
be at all effective, all files used in the boot process up
until the securelevel is set must be protected. If an
attacker can get the system to execute their code prior to
the securelevel being set (which happens quite late in the
boot process since some things the system must do at
start-up cannot be done at an elevated securelevel), its
protections are invalidated. While this task of protecting
all files used in the boot process is not technically
impossible, if it is achieved, system maintenance will
become a nightmare since one would have to take the system
down, at least to single-user mode, to modify a
configuration file.This point and others are often discussed on the
mailing lists, particularly freebsd-security. Please search
the archives here for an
+ url="../../../../search/index.html">here for an
extensive discussion. Some people are hopeful that
securelevel will soon go away in favor of a more
fine-grained mechanism, but things are still hazy in this
respect.Consider yourself warned.How do I let ordinary users mount floppies, CDROMs and other removable
media?Ordinary users can be permitted to mount devices. Here is
how:As root set the sysctl variable
vfs.usermount to
1.&prompt.root; sysctl -w vfs.usermount=1As root assign the appropriate
permissions to the block device associated with the
removable media.For example, to allow users to mount the first floppy
drive, use:&prompt.root; chmod 666 /dev/fd0To allow users in the group
operator to mount the CDROM drive,
use:&prompt.root; chgrp operator /dev/cd0c
&prompt.root; chmod 640 /dev/cd0cFinally, add the line
vfs.usermount=1 to the file
/etc/sysctl.conf so that it is reset
at system boot time.All users can now mount the floppy
/dev/fd0 onto a directory that they
own:&prompt.user; mkdir ~/my-mount-point
&prompt.user; mount -t msdos /dev/fd0 ~/my-mount-pointUsers in group operator can now
mount the CDROM /dev/cd0c onto a
directory that they own:&prompt.user; mkdir ~/my-mount-point
&prompt.user; mount -t msdos /dev/cd0c ~/my-mount-pointUnmounting the device is simple:&prompt.user; umount ~/my-mount-point>Enabling vfs.usermount, however, has
negative security implications. A better way to access MSDOS
formatted media is to use the mtools package in the ports collection.
+ URL="http://www.FreeBSD.org/cgi/ports.cgi?query=%5Emtools-&stype=name">mtools package in the ports collection.
How do I move my system over to my huge new disk?The best way is to reinstall the OS on the new
disk, then move the user data over. This is highly
recommended if you have been tracking -stable for more
than one release, or have updated a release instead of
installing a new one. You can install booteasy on both
disks with &man.boot0cfg.8;, and dual boot them until
you are happy with the new configuration. Skip the
next paragraph to find out how to move the data after
doing this.Should you decide not to do a fresh install, you
need to partition and label the new disk with either
/stand/sysinstall, or &man.fdisk.8;
and &man.disklabel.8;. You should also install booteasy
on both disks with &man.boot0cfg.8;, so that you can
dual boot to the old or new system after the copying
is done. See the
- formatting-media tutorial for details on this
+ url="../../articles/formatting-media/index.html">
+ formatting-media article for details on this
process.Now you have the new disk set up, and are ready
to move the data. Unfortunately, you cannot just blindly
copy the data. Things like device files (in
/dev), flags, and links tend to
screw that up. You need to use tools that understand
these things, which means &man.dump.8;.
Although it is suggested that you move the data in single user
mode, it is not required.You should never use anything but &man.dump.8; and
&man.restore.8; to move the root file system. The
&man.tar.1; command may work - then again, it may not.
You should also use &man.dump.8; and &man.restore.8;
if you are moving a single partition to another empty
partition. The sequence of steps to use dump to move
a partitions data to a new partition is:newfs the new partition.mount it on a temporary mount point.cd to that directory.dump the old partition, piping output to the
new one.For example, if you are going to move root to
/dev/ad1s1a, with
/mnt as the temporary mount point,
it is:&prompt.root; newfs /dev/ad1s1a
&prompt.root; mount /dev/ad1s1a /mnt
&prompt.root; cd /mnt
&prompt.root; dump 0af - / | restore xf -Rearranging your partitions with dump takes a bit more
work. To merge a partition like /var
into it's parent, create the new partition large enough
for both, move the parent partition as described above,
then move the child partition into the empty directory
that the first move created:&prompt.root; newfs /dev/ad1s1a
&prompt.root; mount /dev/ad1s1a /mnt
&prompt.root; cd /mnt
&prompt.root; dump 0af - / | restore xf -
&prompt.root; cd var
&prompt.root; dump 0af - /var | restore xf -To split a directory from it's parent, say putting
/var on it's own partition when it wasn't
before, create both partitions, then mount the child partition
on the approriate directory in the temporary mount point, then
move the old single partition:&prompt.root; newfs /dev/ad1s1a
&prompt.root; newfs /dev/ad1s1d
&prompt.root; mount /dev/ad1s1a /mnt
&prompt.root; mkdir /mnt/var
&prompt.root; mount /dev/ad1s1d /mnt/var
&prompt.root; cd /mnt
&prompt.root; dump 0af - / | restore xf -You might prefer &man.cpio.1;, &man.pax.1;,
&man.tar.1; to &man.dump.8; for user data. At the time of
this writing, these are known to lose file flag information,
so use them with caution.I tried to update my system to the latest -STABLE, but
got -RC or -BETA! What is going on?Short answer: it is just a name. RC stands for
Release Candidate. It signifies that a
release is imminent. In FreeBSD, -BETA is typically synonymous
with the code freeze before a release.Long answer: FreeBSD derives its releases from one of
two places. Major, dot-zero, releases, such as
3.0-RELEASE and 4.0-RELEASE, are branched from the head of
the development stream, commonly referred to as -CURRENT. Minor releases, such
as 3.1-RELEASE or 4.2-RELEASE, have been snapshots of the active
-STABLE branch. Starting with
4.3-RELEASE, each release also now has its own branch which can be
tracked by people requiring an extremely conservative rate
of development (typically only security advisories).When a release is about to be made, the branch from
which it will be derived from has to undergo a certain
process. Part of this process is a code freeze. When a
code freeze is initiated, the name of the branch is
changed to reflect that it is about to become a release.
For example, if the branch used to be called 4.0-STABLE,
its name will be changed to 4.1-BETA to signify the code
freeze and signify that extra pre-release testing should
be happening. Bug fixes can still be committed to be part
of the release. When the source code is in shape for the
release the name will be changed to 4.1-RC to signify that a
release is about to be made from it. Once in the RC stage,
only the most critical bugs found can be fixed.
Once the release, 4.1-RELEASE in this example, has been made,
the branch will be renamed to 4.1-STABLE.I tried to install a new kernel, and the chflags failed.
How do I get around this?Short answer: You are probably at security level
greater than 0. Reboot directly to single user mode to
install the kernel.Long answer: FreeBSD disallows changing system flags
at security levels greater than 0. You can check your
security level with the command:&prompt.root; sysctl kern.securelevelYou cannot lower the security level; you have to boot to
single mode to install the kernel, or change the security
level in /etc/rc.conf then reboot. See
the &man.init.8; man page for details on securelevel, and see
/etc/defaults/rc.conf and the
&man.rc.conf.5; man page for more information on
rc.conf.I cannot change the time on my system by more than one second!
How do I get around this?Short answer: You are probably at security level
greater than 1. Reboot directly to single user mode to
change the date.Long answer: FreeBSD disallows changing the time by
more that one second at security levels greater than 1. You
can check your security level with the command:&prompt.root; sysctl kern.securelevelYou cannot lower the security level; you have to boot
to single mode to change the date, or change the security
level in /etc/rc.conf then reboot. See
the &man.init.8; man page for details on securelevel, and
see /etc/defaults/rc.conf and the
&man.rc.conf.5; man page for more information on rc.conf.Why is rpc.statd using 256 megabytes of
memory?No, there is no memory leak, and it is not using 256 Mbytes
of memory. It simply likes to (i.e., always does) map an
obscene amount of memory into its address space for convenience.
There is nothing terribly wrong with this from a technical
standpoint; it just throws off things like &man.top.1; and
&man.ps.1;.&man.rpc.statd.8; maps its status file (resident on
/var) into its address space; to save
worrying about remapping it later when it needs to grow, it maps
it with a generous size. This is very evident from the source
code, where one can see that the length argument to &man.mmap.2;
is 0x10000000, or one sixteenth of the
address space on an IA32, or exactly 256MB.Why can't I unset the schg file
flag?You are running at an elevated (i.e., greater than 0)
securelevel. Lower the securelevel and try again. For more
information, see the FAQ entry on
securelevel and the &man.init.8; manual page.Why doesn't SSH authentication through
.shosts work by default in recent
versions of FreeBSD?The reason why .shosts
authentication does not work by default in more recent
versions of FreeBSD is because &man.ssh.1;
is not installed suid root by default. To
fix this, you can do one of the
following:As a permanent fix, set
ENABLE_SUID_SSH to true
in /etc/make.conf and rebuild ssh
(or run make world).As a temporary fix, change the mode on
/usr/bin/ssh to 4555
by running chmod 4755 /usr/bin/ssh as
root. Then add
ENABLE_SUID_SSH= true to
/etc/make.conf so the change takes
effect the next time make world is
run.The X Window System and Virtual ConsolesI want to run X, how do I go about it?The easiest way is to simply specify that you want to
run X during the installation process.Then read and follow the documentation on the
xf86config tool, which assists you in configuring
XFree86(tm) for your particular graphics card/mouse/etc.You may also wish to investigate the Xaccel server.
See the section on Xi Graphics or
Metro Link for more details.I tried to run X, but I get an
KDENABIO failed (Operation not permitted)
error when I type startx. What do I do
now?Your system is running at a raised securelevel, is not
it? It is, indeed, impossible to start X at a raised
securelevel. To see why, look at the &man.init.8; man
page.So the question is what else you should do instead,
and you basically have two choices: set your securelevel
back down to zero (usually from /etc/rc.conf),
or run &man.xdm.1; at boot time (before the securelevel is
raised).See for more information about
running &man.xdm.1; at boot time.Why doesn't my mouse work with X?If you are using syscons (the default console driver),
you can configure FreeBSD to support a mouse pointer on each
virtual screen. In order to avoid conflicting with X, syscons
supports a virtual device called
/dev/sysmouse. All mouse events received
from the real mouse device are written to the sysmouse device
via moused. If you wish to use your mouse on one or more
virtual consoles, and use X, see
and set up
moused.Then edit /etc/XF86Config and make
sure you have the following lines.Section Pointer
Protocol "SysMouse"
Device "/dev/sysmouse"
.....The above example is for XFree86 3.3.2 or later. For
earlier versions, the Protocol should be
MouseSystems.Some people prefer to use /dev/mouse
under X. To make this work, /dev/mouse
should be linked to
/dev/sysmouse (see &man.sysmouse.4;):&prompt.root; cd /dev
&prompt.root; rm -f mouse
&prompt.root; ln -s sysmouse mouseMy mouse has a fancy wheel. Can I use it in X?Yes. But you need to customize X client programs. See
Colas Nahaboo's web page
(http://www.inria.fr/koala/colas/mouse-wheel-scroll/)
.If you want to use the imwheel
program, just follow these simple steps.Translate the Wheel EventsThe imwheel program
works by translating mouse button 4 and mouse button 5
events into key events. Thus, you have to get the
mouse driver to translate mouse wheel events to button
4 and 5 events. There are two ways of doing this, the
first way is to have &man.moused.8; do the
translation. The second way is for the X server
itself to do the event translation.Using &man.moused.8; to Translate Wheel
EventsTo have &man.moused.8; perform the event
translations, simply add to
the command line used to start &man.moused.8;.
For example, if you normally start &man.moused.8;
via moused -p /dev/psm0 you
would start it by entering moused -p
/dev/psm0 -z 4 instead. If you start
&man.moused.8; automatically during bootup via
/etc/rc.conf, you can simply
add to the
moused_flags variable in
/etc/rc.conf.You now need to tell X that you have a 5
button mouse. To do this, simply add the line
Buttons 5 to the
Pointer section of
/etc/XF86Config. For
example, you might have the following
Pointer section in
/etc/XF86Config.Pointer Section for Wheeled
Mouse in XFree86 3.3.x series XF86Config with moused
TranslationSection "Pointer"
Protocol "SysMouse"
Device "/dev/sysmouse"
Buttons 5
EndSectionInputDevice Section for Wheeled
Mouse in XFree86 4.x series XF86Config with
automatic protocol recognition and button mapping
TranslationSection "InputDevice"
Identifier "Mouse1"
Driver "mouse"
Option "Protocol" "auto"
Option "Device" "/dev/psm0"
Option "Buttons" "5"
Option "ZAxisMapping" "4 5"
EndSection.emacs example for naive
page scrolling with Wheeled Mouse;; wheel mouse
(global-set-key [mouse-4] 'scroll-down)
(global-set-key [mouse-5] 'scroll-up)Using Your X Server to Translate the Wheel
EventsIf you are not running &man.moused.8;, or if
you do not want &man.moused.8; to translate your
wheel events, you can have the X server do the
event translation instead. This requires a couple
of modifications to your
/etc/XF86Config file. First,
you need to choose the proper protocol for your
mouse. Most wheeled mice use the
IntelliMouse protocol. However,
XFree86 does support other protocols, such as
MouseManPlusPS/2 for the Logitech
MouseMan+ mice. Once you have chosen the protocol
you will use, you need to add a
Protocol line to the
Pointer section.Secondly, you need to tell the X server to
remap wheel scroll events to mouse buttons 4 and
5. This is done with the
ZAxisMapping option.For example, if you are not using
&man.moused.8;, and you have an IntelliMouse
attached to the PS/2 mouse port you would use
the following in
/etc/XF86Config.Pointer Section for Wheeled
Mouse in XF86Config with X
Server TranslationSection "Pointer"
Protocol "IntelliMouse"
Device "/dev/psm0"
ZAxisMapping 4 5
EndSectionInstall imwheelNext, install imwheel
from the Ports collection. It can be found in the
x11 category. This program will
map the wheel events from your mouse into keyboard
events. For example, it might send Page
Up to a program when you scroll the wheel
forwards. Imwheel uses a
configuration file to map the wheel events to
keypresses so that it can send different keys to
different applications. The default
imwheel configuration file
is installed in
/usr/X11R6/etc/imwheelrc. You
can copy it to ~/.imwheelrc and
then edit it if you wish to customize
imwheel's configuration.
The format of the configuration file is documented in
&man.imwheel.1;.Configure Emacs to Work
with Imwheel
(optional)If you use emacs or
Xemacs, then you need to
add a small section to your
~/.emacs file. For
emacs, add the
following:Emacs Configuration
for Imwheel;;; For imwheel
(setq imwheel-scroll-interval 3)
(defun imwheel-scroll-down-some-lines ()
(interactive)
(scroll-down imwheel-scroll-interval))
(defun imwheel-scroll-up-some-lines ()
(interactive)
(scroll-up imwheel-scroll-interval))
(global-set-key [?\M-\C-\)] 'imwheel-scroll-up-some-lines)
(global-set-key [?\M-\C-\(] 'imwheel-scroll-down-some-lines)
;;; end imwheel sectionFor Xemacs, add the
following to your ~/.emacs file
instead:Xemacs Configuration
for Imwheel;;; For imwheel
(setq imwheel-scroll-interval 3)
(defun imwheel-scroll-down-some-lines ()
(interactive)
(scroll-down imwheel-scroll-interval))
(defun imwheel-scroll-up-some-lines ()
(interactive)
(scroll-up imwheel-scroll-interval))
(define-key global-map [(control meta \))] 'imwheel-scroll-up-some-lines)
(define-key global-map [(control meta \()] 'imwheel-scroll-down-some-lines)
;;; end imwheel sectionRun ImwheelYou can just type imwheel
in an xterm to start it up once it is installed. It
will background itself and take effect immediately.
If you want to always use
imwheel, simply add it to
your .xinitrc or
.xsession file. You can safely
ignore any warnings imwheel
displays about PID files. Those warnings only apply
to the Linux version of
imwheel.Why do X Window menus and dialog boxes not work right?Try turning off the Num Lock key.If your Num Lock key is on by default at boot-time, you
may add the following line in the Keyboard
section of the XF86Config file.# Let the server do the NumLock processing. This should only be
# required when using pre-R6 clients
ServerNumLockWhat is a virtual console and how do I make more?Virtual consoles, put simply, enable you to have several
simultaneous sessions on the same machine without doing anything
complicated like setting up a network or running X.When the system starts, it will display a login prompt on
the monitor after displaying all the boot messages. You can
then type in your login name and password and start working (or
playing!) on the first virtual console.At some point, you will probably wish to start another
session, perhaps to look at documentation for a program
you are running or to read your mail while waiting for an
FTP transfer to finish. Just do Alt-F2 (hold down the Alt
key and press the F2 key), and you will find a login prompt
waiting for you on the second virtual console!
When you want to go back to the original session, do
Alt-F1.The default FreeBSD installation has three virtual consoles
enabled (8 starting with 3.3-RELEASE), and Alt-F1, Alt-F2, and
Alt-F3 will switch between these virtual consoles.To enable more of them, edit
/etc/ttys (see &man.ttys.5;)
and add entries for ttyv4
to ttyvc after the comment on
Virtual terminals:# Edit the existing entry for ttyv3 in /etc/ttys and change
# "off" to "on".
ttyv3 "/usr/libexec/getty Pc" cons25 on secure
ttyv4 "/usr/libexec/getty Pc" cons25 on secure
ttyv5 "/usr/libexec/getty Pc" cons25 on secure
ttyv6 "/usr/libexec/getty Pc" cons25 on secure
ttyv7 "/usr/libexec/getty Pc" cons25 on secure
ttyv8 "/usr/libexec/getty Pc" cons25 on secure
ttyv9 "/usr/libexec/getty Pc" cons25 on secure
ttyva "/usr/libexec/getty Pc" cons25 on secure
ttyvb "/usr/libexec/getty Pc" cons25 on secureUse as many or as few as you want. The more virtual
terminals you have, the more resources that are used; this
can be important if you have 8MB RAM or less. You may also
want to change the secure
to insecure.If you want to run an X server you
must leave at least one virtual
terminal unused (or turned off) for it to use. That is to
say that if you want to have a login prompt pop up for all
twelve of your Alt-function keys, you are out of luck - you
can only do this for eleven of them if you also want to run
an X server on the same machine.The easiest way to disable a console is by turning it off.
For example, if you had the full 12 terminal allocation
mentioned above and you wanted to run X, you would change
settings for virtual terminal 12 from:ttyvb "/usr/libexec/getty Pc" cons25 on secureto:ttyvb "/usr/libexec/getty Pc" cons25 off secureIf your keyboard has only ten function keys, you would
end up with:ttyv9 "/usr/libexec/getty Pc" cons25 off secure
ttyva "/usr/libexec/getty Pc" cons25 off secure
ttyvb "/usr/libexec/getty Pc" cons25 off secure(You could also just delete these lines.)Once you have edited
/etc/ttys, the next step is to make sure that you
have enough virtualterminal devices. The easiest way to do
this is:&prompt.root; cd /dev
&prompt.root; sh MAKEDEV vty12Next, the easiest (and cleanest) way to activate the
virtual consoles is to reboot. However, if you really do not
want to reboot, you can just shut down the X Window system
and execute (as root):&prompt.root; kill -HUP 1It is imperative that you completely shut down X Window if
it is running, before running this command. If you don't,
your system will probably appear to hang/lock up after
executing the kill command.How do I access the virtual consoles from X?Use CtrlAltFn to switch back to a virtual console.
CtrlAltF1 would return you to the first virtual console.Once you are back to a text console, you can then use
AltFn as normal to move between them.To return to the X session, you must switch to the virtual
console running X. If you invoked X from the command line, (e.g.,
using startx) then the X session will attach to
the next unused virtual console, not the text console from which
it was invoked. If you have eight active virtual terminals then X
will be running on the ninth, and you would use
AltF9 to return.How do I start XDM on boot?There are two schools of thought on how to start
xdm. One school starts xdm from
/etc/ttys (see &man.ttys.5;)
using the supplied example, while the other simply runs xdm
from
rc.local (see &man.rc.8;)
or from a X.sh script in
/usr/local/etc/rc.d. Both are equally
valid, and one may work in situations where the other does not.
In both cases the result is the same: X will popup a graphical
login: prompt.The ttys method has the advantage of documenting which
vty X will start on and passing the responsibility of
restarting the X server on logout to init. The rc.local
method makes it easy to kill xdm if there is a problem
starting the X server.If loaded from rc.local, xdm should
be started without any arguments (i.e., as a daemon). xdm must
start AFTER getty runs, or else getty and xdm will conflict,
locking out the console. The best way around this is to have
the script sleep 10 seconds or so then launch xdm.If you are to start xdm from
/etc/ttys, there still is a chance of
conflict between xdm and
&man.getty.8;. One way to avoid this is to add the
vt number in the
/usr/X11R6/lib/X11/xdm/Xservers
file.:0 local /usr/X11R6/bin/X vt4The above example will direct the X server to run in
/dev/ttyv3. Note the number is offset by
one. The X server counts the vty from one, whereas the FreeBSD
kernel numbers the vty from zero.Why do I get Couldn't open console
when I run xconsole?If you start X
with
startx, the permissions on
/dev/console will
not get changed, resulting in
things like
xterm -C and
xconsole not working.This is because of the way console permissions are set
by default. On a multi-user system, one does not necessarily
want just any user to be able to write on the system console.
For users who are logging directly onto a machine with a VTY,
the &man.fbtab.5;
file exists to solve such problems.In a nutshell, make sure an uncommented line of the
form/dev/ttyv0 0600 /dev/consoleis in
/etc/fbtab (see &man.fbtab.5;) and it will ensure that whomever logs in on
/dev/ttyv0 will own the console.Before, I was able to run XFree86 as a regular user. Why does
it now say that I must be root?All X servers need to be run as root in order to get direct
access to your video hardware. Older versions of XFree86
(<= 3.3.6) installed all bundled servers to be automatically
run as root (setuid to root). This is obviously a security
hazard because X servers are large, complicated programs.
Newer versions of XFree86 do not install the servers setuid to
root for just this reason.Obviously, running an X server as the root user is not
acceptable, nor a good idea security-wise. There are two ways
to be able to use X as a regular user. The first is to use
xdm or another display manager
(e.g., kdm); the second is to use the
Xwrapper.xdm is a daemon that handles graphical
logins. It is usually started at boot time, and is responsible
for authenticating users and starting their sessions; it is
essentially the graphical counterpart of
&man.getty.8; and &man.login.1;. For
more information on xdm see
the XFree86
documentation, and the the FAQ
entry on it.Xwrapper is the X server wrapper; it is
a small utility to enable one to manually run an X server while
maintaining reasonable safety. It performs some sanity checks
on the command line arguments given, and if they pass, runs the
appropriate X server. If you do not want to run a display
manger for whatever reason, this is for you. If you have
installed the complete ports collection, you can find the port in
/usr/ports/x11/wrapper.Why does my PS/2 mouse misbehave under X?Your mouse and the mouse driver may have somewhat become
out of synchronization.In versions 2.2.5 and earlier, switching away from X to a
virtual terminal and getting back to X again may make them
re-synchronized. If the problem occurs often, you may add the
following option in your kernel configuration file and
recompile it.options PSM_CHECKSYNCSee the section on building
a kernel if you have no experience with building
kernels.With this option, there should be less chance of
synchronization problem between the mouse and the driver.
If, however, you still see the problem, click any mouse
button while holding the mouse still to re-synchronize the
mouse and the driver.Note that unfortunately this option may not work with all
the systems and voids the tap feature of the
ALPS GlidePoint device attached to the PS/2 mouse port.In versions 2.2.6 and later, synchronization check is done
in a slightly better way and is standard in the PS/2 mouse
driver. It should even work with GlidePoint. (As the check code
has become a standard feature, PSM_CHECKSYNC option is not
available in these versions.) However, in rare case the driver
may erroneously report synchronization problem and you may see
the kernel message:psmintr: out of sync (xxxx != yyyy)and find your mouse does not seem to work properly.If this happens, disable the synchronization check code
by setting the driver flags for the PS/2 mouse driver to 0x100.
Enter UserConfig by giving the
option at the boot prompt:boot: -cThen, in the UserConfig command
line, type:UserConfig> flags psm0 0x100
UserConfig> quitHow come my PS/2 mouse from MouseSystems does not seem
to work?There have been some reports that certain model of PS/2
mouse from MouseSystems works only if it is put into the
high resolution mode. Otherwise, the mouse
cursor may jump to the upper-left corner of the screen every
so often.Unfortunately there is no workaround for versions 2.0.X
and 2.1.X. In versions 2.2 through 2.2.5, apply the following
patch to /sys/i386/isa/psm.c and rebuild
the kernel. See the section on building a kernel if you have no
experience with building kernels.@@ -766,6 +766,8 @@
if (verbose >= 2)
log(LOG_DEBUG, "psm%d: SET_DEFAULTS return code:%04x\n",
unit, i);
+ set_mouse_resolution(sc->kbdc, PSMD_RES_HIGH);
+
#if 0
set_mouse_scaling(sc->kbdc); /* 1:1 scaling */
set_mouse_mode(sc->kbdc); /* stream mode */In versions 2.2.6 or later, specify the flags 0x04 to
the PS/2 mouse driver to put the mouse into the high
resolution mode. Enter UserConfig by
giving the option at the boot prompt:boot: -cThen, in the UserConfig command line,
type:UserConfig> flags psm0 0x04
UserConfig> quitSee the previous section for another possible cause of mouse
problems.When building an X app, imake cannot
find Imake.tmpl. Where is it?Imake.tmpl is part of the Imake package, a standard X
application building tool. Imake.tmpl, as well as several
header files that are required to build X apps, is contained
in the X prog distribution. You can install this from sysinstall
or manually from the X distribution files.How do I reverse the mouse buttons?Run the command
xmodmap -e "pointer = 3 2 1" from your
.xinitrc or .xsession.How do I install a splash screen and where do I find
them?Just prior to the release of FreeBSD 3.1, a new feature
was added to allow the display of splash screens
during the boot messages. The splash screens currently must be
a 256 color bitmap (*.BMP) or ZSoft PCX
(*.PCX) file. In addition, they must have
a resolution of 320x200 or less to work on standard VGA
adapters. If you compile VESA support into your kernel, then
you can use larger bitmaps up to 1024x768. Note that VESA
support requires the VM86 kernel option to
be compiled into the kernel. The actual VESA support can either
be compiled directly into the kernel with the
VESA kernel config option or by loading the
VESA kld module during bootup.To use a splash screen, you need to modify the startup
files that control the boot process for FreeBSD. The files for
this changed prior to the release of FreeBSD 3.2, so there are
now two ways of loading a splash screen:FreeBSD 3.1The first step is to find a bitmap version of your
splash screen. Release 3.1 only supports Windows bitmap
splash screens. Once you have found your splash screen of
choice copy it to /boot/splash.bmp.
Next, you need to have a
/boot/loader.rc file that contains
the following lines:load kernel
load -t splash_image_data /boot/splash.bmp
load splash_bmp
autobootFreeBSD 3.2+In addition to adding support for PCX splash screens,
FreeBSD 3.2 includes a nicer way of configuring the boot
process. If you wish, you can use the method listed above
for FreeBSD 3.1. If you do and you want to use PCX,
replace splash_bmp with
splash_pcx. If, on the other hand, you
want to use the newer boot configuration, you need to
create a /boot/loader.rc file that
contains the following lines:include /boot/loader.4th
startand a /boot/loader.conf that
contains the following:splash_bmp_load="YES"
bitmap_load="YES"This assumes you are using
/boot/splash.bmp for your splash
screen. If you would rather use a PCX file, copy it to
/boot/splash.pcx, create a
/boot/loader.rc as instructed
above, and create a
/boot/loader.conf that
contains:splash_pcx_load="YES"
bitmap_load="YES"
bitmap_name="/boot/splash.pcx"Now all you need is a splash screen. For that you can
surf on over to the gallery at http://www.baldwin.cx/splash/.Can I use the Windows(tm) keys on my keyboard in X?Yes. All you need to do is use &man.xmodmap.1; to define
what function you wish them to perform.Assuming all Windows(tm) keyboards are
standard then the keycodes for the 3 keys are115 - Windows(tm) key, between the left-hand Ctrl and
Alt keys116 - Windows(tm) key, to the right of the Alt-Gr
key117 - Menu key, to the left of the right-hand Ctrl
keyTo have the left Windows(tm) key print a comma, try
this.&prompt.root; xmodmap -e "keycode 115 = comma"You will probably have to re-start your window manager
to see the result.To have the Windows(tm) key-mappings enabled automatically
every time you start X either put the xmodmap
commands in your ~/.xinitrc file or,
preferably, create a file ~/.xmodmaprc and
include the xmodmap options, one per line,
then add the linexmodmap $HOME/.xmodmaprcto your ~/.xinitrc.For example, you could map the 3 keys top be F13, F14, and
F15, respectively. This would make it easy to map them to
useful functions within applications or your window
manager, as demonstrated further down.To do this put the following in
~/.xmodmaprc.keycode 115 = F13
keycode 116 = F14
keycode 117 = F15If you use fvwm2, for example, you
could map the keys
so that F13 iconifies (or de-iconifies) the window the cursor
is in, F14 brings the window the cursor is in to the front or,
if it is already at the front, pushes it to the back, and F15
pops up the main Workplace (application) menu even if the
cursor is not on the desktop, which is useful if you do not have
any part of the desktop visible (and the logo on the key
matches its functionality).The following entries in
~/.fvwmrc implement the
aforementioned setup:Key F13 FTIWS A Iconify
Key F14 FTIWS A RaiseLower
Key F15 A A Menu Workplace NopNetworkingWhere can I get information on
diskless booting?Diskless booting means that the FreeBSD
box is booted over a network, and reads the necessary files
from a server instead of its hard disk. For full details,
please read the
Handbook entry on diskless bootingCan a FreeBSD box be used as a dedicated network
router?Internet standards and good engineering practice prohibit
us from providing packet forwarding by default in FreeBSD. You
can however enable this feature by changing the following
variable to YES in
&man.rc.conf.5;:gateway_enable=YES # Set to YES if this host will be a gatewayThis option will put the
&man.sysctl.8; variable
net.inet.ip.forwarding
to 1.In most cases, you will also need to run a routing process
to tell other systems on your network about your router;
FreeBSD comes with the standard BSD routing daemon
&man.routed.8;
or for more complex situations you may want to try
GaTeD (available from http://www.gated.org/)
which supports FreeBSD as of 3_5Alpha7.It is our duty to warn you that, even when FreeBSD is
configured in this way, it does not completely comply with
the Internet standard requirements for routers; however,
it comes close enough for ordinary usage.Can I connect my Win95 box to the Internet via
FreeBSD?Typically, people who ask this question have two PC's
at home, one with FreeBSD and one with Win95; the idea is to
use the FreeBSD box to connect to the Internet and then be able
to access the Internet from the Windows95 box through the
FreeBSD box. This is really just a special case of the previous
question.... and the answer is yes! In FreeBSD
3.x, user-mode ppp contains a option. If
you run ppp with the ,
set gateway_enable to
YES in /etc/rc.conf,
and configure your Windows machine correctly, this should work
fine.More detailed information about setting this up can be
found in the
+ URL="../ppp-primer/index.html">
Pedantic PPP Primer by Steve Sims.If you are using kernel-mode ppp, or have an Ethernet
connection to the Internet, you will have to use
&man.natd.8;. Please look at the
natd section of this FAQ.Why does recompiling the latest BIND from ISC fail?There is a conflict between the
cdefs.h file in the distribution and the
one shipped with FreeBSD. Just remove
compat/include/sys/cdefs.h.Does FreeBSD support SLIP and PPP?Yes. See the manual pages for &man.slattach.8;,
&man.sliplogin.8;, &man.ppp.8;, and &man.pppd.8;. &man.ppp.8;
and &man.pppd.8; provide support for both incoming and outgoing
connections, while &man.sliplogin.8; deals exclusively with
incoming connections, and &man.slattach.8; deals exclusively
with outgoing connections.For more information on how to use these, please see the
Handbook chapter on
PPP and SLIP.If you only have access to the Internet through a
shell account, you may want to have a look at
the
slirp package. It can provide you with (limited)
access to services such as ftp and http direct from your local
machine.Does FreeBSD support NAT or Masquerading?If you have a local subnet (one or more local machines),
but have been allocated only a single IP number from your
Internet provider (or even if you receive a dynamic IP number),
you may want to look at the &man.natd.8;
program. &man.natd.8; allows you to connect an
entire subnet to the Internet using only a single IP
number.The &man.ppp.8;
program has similar functionality built in via
the switch. The
alias library (&man.libalias.3;) is used in both cases.How do I connect two FreeBSD systems over a parallel line
using PLIP?Get a laplink cable. Make sure both computer have a kernel
with lpt driver support.&prompt.root; dmesg | grep lp
lpt0 at 0x378-0x37f irq 7 on isa
lpt0: Interrupt-driven
lp0: TCP/IP capable interfacePlug in the laplink cable into the parallel interface.Configure the network interface parameters for lp0 on both
sites as root. For example, if you want connect the host max
with moritz max <-----> moritz
IP Address 10.0.0.1 10.0.0.2on max start&prompt.root; ifconfig lp0 10.0.0.1 10.0.0.2on moritz start&prompt.root; ifconfig lp0 10.0.0.2 10.0.0.1Thats all! Please read also the manpages
&man.lp.4; and &man.lpt.4; .You should also add the hosts to
/etc/hosts.127.0.0.1 localhost.my.domain localhost
10.0.0.1 max.my.domain max
10.0.0.2 moritz.my.domainTo check if it works do:on max:&prompt.root; ifconfig lp0
lp0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000
&prompt.root; netstat -r
Routing tables
Internet:
Destination Gateway Flags Refs Use Netif Expire
moritz max UH 4 127592 lp0
&prompt.root; ping -c 4 moritz
PING moritz (10.0.0.2): 56 data bytes
64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
--- moritz ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 msHow come I cannot create a /dev/ed0
device?In the Berkeley networking framework, network interfaces
are only directly accessible by kernel code. Please see the
/etc/rc.network file and the manual pages
for the various network programs mentioned there for more
information. If this leaves you totally confused, then you
should pick up a book describing network administration on
another BSD-related operating system; with few significant
exceptions, administering networking on FreeBSD is basically
the same as on SunOS 4.0 or Ultrix.How can I setup Ethernet aliases?Add netmask 0xffffffff to your
&man.ifconfig.8; command-line like the following:&prompt.root; ifconfig ed0 alias 204.141.95.2 netmask 0xffffffffHow do I get my 3C503 to use the other network
port?If you want to use the other ports, you will have to specify
an additional parameter on the
&man.ifconfig.8; command line. The default port is
link0. To use the AUI port instead of the
BNC one, use link2. These flags should be
specified using the ifconfig_* variables in
/etc/rc.conf (see &man.rc.conf.5;).Why am I having trouble with NFS and FreeBSD?Certain PC network cards are better than others (to put
it mildly) and can sometimes cause problems with network
intensive applications like NFS.See
the Handbook entry on NFS for more information on
this topic.Why can't I NFS-mount from a Linux box?Some versions of the Linux NFS code only accept mount
requests from a privileged port; try&prompt.root; mount -o -P linuxbox:/blah /mntWhy can't I NFS-mount from a Sun box?Sun workstations running SunOS 4.X only accept mount
requests from a privileged port; try&prompt.root; mount -o -P sunbox:/blah /mntWhy does mountd keep telling me it
can't change attributes and that I have a
bad exports list on my FreeBSD NFS
server?The most frequent problem is not understanding this
passage from the &man.exports.5; manual page
correctly:
Each line in the file (other than comment
lines that begin with a #) specifies the mount point(s)
and export flags within one local server filesystem for
one or more hosts. A host may be specified only once
for each local filesystem on the server and there may be
only one default entry for each server filesystem that
applies to all other hosts.
This is made more clear by an example of a common
mistake. If everything above /usr is
part of one filesystem (there are no mounts above
/usr) the following exports list is
not valid:/usr/src client
/usr/ports clientThere are two lines specifying properties for one
filesystem, /usr, exported to the
same host, client. The correct format
is:/usr/src /usr/ports clientTo rephrase the passage from the manual page, the
properties of one filesystem exported to a given host
(world-wide exports are treated like another unique host)
must all occur on one line. And yes, this does cause
limitation in how you can export filesystems without ugly
workarounds, but for most people, this is not an
issue.The following is an example of a valid export list,
where /usr and
/exports are local
filesystems:# Export src and ports to client01 and client02, but only
# client01 has root privileges on it
/usr/src /usr/ports -maproot=0 client01
/usr/src /usr/ports client02
# The "client" machines have root and can mount anywhere
# up /exports. The world can mount /exports/obj read-only
/exports -alldirs -maproot=0 client01 client02
/exports/obj -roWhy am I having problems talking PPP to NeXTStep
machines?Try disabling the TCP extensions in
/etc/rc.conf (see &man.rc.conf.5;) by changing the following variable to
NO:tcp_extensions=NOXylogic's Annex boxes are also broken in this regard and
you must use the above change to connect thru them.How do I enable IP multicast support?Multicast host operations are fully supported in FreeBSD
2.0 and later by default. If you want your box to run as a
multicast router, you will need to recompile your kernel with
the MROUTING option and run
&man.mrouted.8;. FreeBSD 2.2 and later will start
&man.mrouted.8; at boot time if the flag
mrouted_enable is set to
"YES" in
/etc/rc.conf.MBONE tools are available in their own ports category,
mbone. If you are looking for the conference tools
vic and vat,
look there!For more information, see the Mbone Information Web.Which network cards are based on the DEC PCI
chipset?Here is a list compiled by Glen Foster
gfoster@driver.nsta.org,
with some more modern additions:
Network cards based on the DEC PCI chipsetVendorModelASUSPCI-L101-TBAcctonENI1203CogentEM960PCICompexENET32-PCID-LinkDE-530DaynaDP1203, DP2100DECDE435, DE450DanpexEN-9400P3JCISCondor JC1260LinksysEtherPCIMylexLNP101SMCEtherPower 10/100 (Model 9332)SMCEtherPower (Model 8432)TopWareTE-3500PZnyx (2.2.x)ZX312, ZX314, ZX342, ZX345, ZX346, ZX348Znyx (3.x)ZX345Q, ZX346Q, ZX348Q, ZX412Q, ZX414, ZX442, ZX444,
ZX474, ZX478, ZX212, ZX214 (10mbps/hd)
Why do I have to use the FQDN for hosts on my
site?You will probably find that the host is actually in a
different domain; for example, if you are in foo.example.org and
you wish to reach a host called mumble in the
example.org domain, you will
have to refer to it by the fully-qualified domain name, mumble.example.org, instead of just
mumble.Traditionally, this was allowed by BSD BIND resolvers.
However the current version of
bind (see &man.named.8;)
that ships with FreeBSD no longer provides default
abbreviations for non-fully qualified domain names other than
the domain you are in. So an unqualified host
mumble must either be found as mumble.foo.example.org, or it will be searched
for in the root domain.This is different from the previous behavior, where the
search continued across
mumble.example.org, and
mumble.edu. Have a look at
RFC 1535 for why this was considered bad practice, or even a
security hole.As a good workaround, you can place the linesearch foo.example.org example.orginstead of the previousdomain foo.example.orginto your
/etc/resolv.conf file (see &man.resolv.conf.5;). However, make sure that the
search order does not go beyond the boundary between
local and public administration, as RFC 1535 calls
it.Why do I get an error, Permission denied,
for all networking operations?If you have compiled your kernel with the
IPFIREWALL option, you need to be aware
that the default policy as of 2.1.7R (this actually changed
during 2.1-STABLE development) is to deny all packets that are
not explicitly allowed.If you had unintentionally misconfigured your system for
firewalling, you can restore network operability by typing
the following while logged in as root:&prompt.root; ipfw add 65534 allow all from any to anyYou can also set firewall_type="open"
in /etc/rc.conf.For further information on configuring a FreeBSD firewall,
see the
Handbook section.How much overhead does IPFW incur?The answer to this depends mostly on your rule set and
processor speed. For most applications dealing with Ethernet
and small rule sets, the answer is, negligible. For those of
you that need actual measurements to satisfy your curiosity,
read on.The following measurements were made using 2.2.5-STABLE
on a 486-66. IPFW was modified to measure the time spent
within the ip_fw_chk routine, displaying
the results to the console every 1000 packets.Two rule sets, each with 1000 rules were tested. The
first set was designed to demonstrate a worst case scenario
by repeating the rule:&prompt.root; ipfw add deny tcp from any to any 55555This demonstrates worst case by causing most of IPFW's
packet check routine to be executed before finally deciding
that the packet does not match the rule (by virtue of the port
number). Following the 999th iteration of this rule was an
allow ip from any to any.The second set of rules were designed to abort the rule
check quickly:&prompt.root; ipfw add deny ip from 1.2.3.4 to 1.2.3.4The nonmatching source IP address for the above rule causes
these rules to be skipped very quickly. As before, the 1000th
rule was an allow ip from any to any.The per-packet processing overhead in the former case was
approximately 2.703ms/packet, or roughly 2.7 microseconds per
rule. Thus the theoretical packet processing limit with these
rules is around 370 packets per second. Assuming 10Mbps
Ethernet and a ~1500 byte packet size, we would only be able to
achieve a 55.5% bandwidth utilization.For the latter case each packet was processed in
approximately 1.172ms, or roughly 1.2 microseconds per rule.
The theoretical packet processing limit here would be about
853 packets per second, which could consume 10Mbps Ethernet
bandwidth.The excessive number of rules tested and the nature of
those rules do not provide a real-world scenario -- they were
used only to generate the timing information presented here.
Here are a few things to keep in mind when building an
efficient rule set:Place an established rule early
on to handle the majority of TCP traffic. Do not put any
allow tcp statements before this
rule.Place heavily triggered rules earlier in the rule
set than those rarely used (without
changing the permissiveness of the firewall,
of course). You can see which rules are used most often
by examining the packet counting statistics with
ipfw -a l.Why is my ipfwfwd rule
to redirect a service to another machine not working?Possibly because you want to do network address translation
(NAT) and not just forward packets. A fwd rule
does exactly what it says; it forwards packets. It does not
actually change the data inside the packet. Say we have a rule
like:01000 fwd 10.0.0.1 from any to foo 21When a packet with a destination address of
foo arrives at the machine with this
rule, the packet is forwarded to
10.0.0.1, but it still has the
destination address of foo! The
destination address of the packet is not
changed to 10.0.0.1. Most machines
would probably drop a packet that they receive with a
destination address that is not their own. Therefore, using a
fwd rule does not often work the way the user
expects. This behavior is a feature and not a bug.See the FAQ about
redirecting services, the &man.natd.8; manual, or one of
the several port redirecting utilities in the ports collection for a correct way to do
+ url="../../../../ports/index.html">ports collection for a correct way to do
this.How can I redirect service requests from one machine to
another?You can redirect FTP (and other service) request with
the socket package, available in the ports
tree in category sysutils. Simply replace the
service's commandline to call socket instead, like so:ftp stream tcp nowait nobody /usr/local/bin/socket socket ftp.example.comftpwhere ftp.example.com and
ftp are the host and port to
redirect to, respectively.Where can I get a bandwidth management tool?There are three bandwidth management tools available for
FreeBSD. &man.dummynet.4; is integreated into FreeBSD (or more
specifically, &man.ipfw.4;); ALTQ
is available for free; Bandwidth Manager from Emerging Technologies is a
commercial product.BIND (named) is listening on port 53 and
some other high-numbered port. Has my host been
compromised?Probably not. FreeBSD 3.0 and later use a version of BIND
that uses a random high-numbered port for outgoing queries. If
you want to use port 53 for outgoing queries, either to get
past a firewall or to make yourself feel better, you can try
the following in
/etc/namedb/named.conf:options {
query-source address * port 53;
};You can replace the * with a single IP
address if you want to tighten things further.Congratulations, by the way. It is good practice to read
your &man.sockstat.1; output and notice odd
things!Why do I get /dev/bpf0: device not
configured?The Berkeley Packet Filter (&man.bpf.4;)
driver needs to be enabled before running programs that
utilize it. Add this to your kernel config file and build
a new kernel:pseudo-device bpf # Berkeley Packet FilterSecondly, after rebooting you will have to create the
device node. This can be accomplished by a change to the
/dev directory, followed by the execution
of:&prompt.root; sh MAKEDEV bpf0Please see the
handbook's entry on device nodes for more information
on creating devices.How do I mount a disk from a Windows machine that is on my
network, like smbmount in Linux?Use the sharity light
package in the ports collection.What are these messages about icmp-response
bandwidth limit 300/200 pps in my log
files?This is the kernel telling you that some activity is
provoking it to send more ICMP or TCP reset (RST)
responses than it thinks it should. ICMP responses are
often generated as a result of attempted connections to
unused UDP ports. TCP resets are generated as a result of
attempted connections to unopened TCP ports. Among
others, these are the kinds of activities which may cause
these messages:Brute-force denial of service (DoS) attacks (as
opposed to single-packet attacks which exploit a
specific vulnerability).Port scans which attempt to connect to a large
number of ports (as opposed to only trying a few
well-known ports).The first number in the message tells you how many
packets the kernel would have sent if the limit was not in
place, and the second number tells you the limit. You can
control the limit using the
net.inet.icmp.icmplim sysctl variable
like this, where 300 is the limit in
packets per second:&prompt.root; sysctl -w net.inet.icmp.icmplim=300If you do not want to see messages about this in your
log files, but you still want the kernel to do response
limiting, you can use the
net.inet.icmp.icmplim_output sysctl
variable to disable the output like this:&prompt.root; sysctl -w net.inet.icmp.icmplim_output=0Finally, if you want to disable response limiting, you
can set the net.inet.icmp.icmplim
sysctl variable (see above for an example) to
0. Disabling response limiting is
discouraged for the reasons listed above.PPPI cannot make &man.ppp.8; work. What am I doing wrong?You should first read the
&man.ppp.8;
man page and the
ppp section of the handbook. Enable logging with
the commandset log Phase Chat Connect Carrier lcp ipcp ccp commandThis command may be typed at the
ppp command prompt or it may be
entered in the /etc/ppp/ppp.conf
configuration file (the start of the
default section is the best
place to put it). Make sure that
/etc/syslog.conf (see &man.syslog.conf.5;) contains the lines!ppp
*.* /var/log/ppp.logand that the file /var/log/ppp.log
exists. You can now find out a lot about what is going on
from the log file. Do not worry if it does not all make sense.
If you need to get help from someone, it may make sense to
them.If your version of ppp does not understand the
set log command, you should download the
latest version. It will build on FreeBSD version
2.1.5 and higher.Why does &man.ppp.8; hang when I run it?This is usually because your hostname will not resolve.
The best way to fix this is to make sure that
/etc/hosts is consulted by your
resolver first by editing /etc/host.conf
and putting the hosts line first. Then,
simply put an entry in /etc/hosts for
your local machine. If you have no local network, change your
localhost line:127.0.0.1 foo.bar.com foo localhostOtherwise, simply add another entry for your host.
Consult the relevant man pages for more details.You should be able to successfully
ping -c1 `hostname` when you are done.Why won't &man.ppp.8; dial in -auto
mode?First, check that you have got a default route. By running
netstat -rn (see &man.netstat.1;), you should see two entries like this:Destination Gateway Flags Refs Use Netif Expire
default 10.0.0.2 UGSc 0 0 tun0
10.0.0.2 10.0.0.1 UH 0 0 tun0This is assuming that you have used the addresses from the
handbook, the man page or from the ppp.conf.sample file.
If you haven't got a default route, it may be because you are
running an old version of &man.ppp.8;
that does not understand the word HISADDR
in the ppp.conf file. If your version of
ppp is from before FreeBSD
2.2.5, change theadd 0 0 HISADDRline to one sayingadd 0 0 10.0.0.2Another reason for the default route line being missing
is that you have mistakenly set up a default router in your
/etc/rc.conf (see &man.rc.conf.5;) file (this file was called
/etc/sysconfig prior to release 2.2.2),
and you have omitted the line sayingdelete ALLfrom ppp.conf. If this is the case,
go back to the
Final system configuration section of the
handbook.What does No route to host mean?This error is usually due to a missingMYADDR:
delete ALL
add 0 0 HISADDRsection in your /etc/ppp/ppp.linkup
file. This is only necessary if you have a dynamic IP address
or do not know the address of your gateway. If you are using
interactive mode, you can type the following after entering
packet mode (packet mode is
indicated by the capitalized PPP in the
prompt):delete ALL
add 0 0 HISADDRRefer to the
PPP and Dynamic IP addresses section of the handbook
for further details.Why does my connection drop after about 3 minutes?The default ppp timeout is 3 minutes. This can be
adjusted with the lineset timeout NNNwhere NNN is the number of
seconds of inactivity before the connection is closed. If
NNN is zero, the connection is never
closed due to a timeout. It is possible to put this command in
the ppp.conf file, or to type it at the
prompt in interactive mode. It is also possible to adjust it on
the fly while the line is active by connecting to
ppps server socket using
&man.telnet.1; or &man.pppctl.8;.
Refer to the
&man.ppp.8; man
page for further details.Why does my connection drop under heavy load?If you have Link Quality Reporting (LQR) configured,
it is possible that too many LQR packets are lost between
your machine and the peer. Ppp deduces that the line must
therefore be bad, and disconnects. Prior to FreeBSD version
2.2.5, LQR was enabled by default. It is now disabled by
default. LQR can be disabled with the linedisable lqrWhy does my connection drop after a random amount of
time?Sometimes, on a noisy phone line or even on a line with
call waiting enabled, your modem may hang up because it
thinks (incorrectly) that it lost carrier.There is a setting on most modems for determining how
tolerant it should be to temporary losses of carrier. On a
USR Sportster for example, this is measured by the S10
register in tenths of a second. To make your modem more
forgiving, you could add the following send-expect sequence
to your dial string:set dial "...... ATS10=10 OK ......"Refer to your modem manual for details.Why does my connection hang after a random amount of
time?Many people experience hung connections with no apparent
explanation. The first thing to establish is which side of
the link is hung.If you are using an external modem, you can simply try
using &man.ping.8; to see if the
TD light is flashing when you transmit data.
If it flashes (and the RD light does not),
the problem is with the remote end. If TD
does not flash, the problem is local. With an internal modem,
you will need to use the set server command in
your ppp.conf file. When the hang occurs,
connect to ppp using pppctl. If your network connection
suddenly revives (ppp was revived due to the activity on the
diagnostic socket) or if you cannot connect (assuming the
set socket command succeeded at startup
time), the problem is local. If you can connect and things are
still hung, enable local async logging with set log
local async and use &man.ping.8; from
another window or terminal to make use of the link. The async
logging will show you the data being transmitted and received
on the link. If data is going out and not coming back, the
problem is remote.Having established whether the problem is local or remote,
you now have two possibilities:The remote end is not responding. What can I do?There is very little you can do about this. Most ISPs
will refuse to help if you are not running a Microsoft OS.
You can enable lqr in your
ppp.conf file, allowing ppp to detect
the remote failure and hang up, but this detection is
relatively slow and therefore not that useful. You may want to
avoid telling your ISP that you are running user-ppp....First, try disabling all local compression by adding the
following to your configuration:disable pred1 deflate deflate24 protocomp acfcomp shortseq vj
deny pred1 deflate deflate24 protocomp acfcomp shortseq vjThen reconnect to ensure that this makes no difference.
If things improve or if the problem is solved completely,
determine which setting makes the difference through trial
and error. This will provide good ammunition when you contact
your ISP (although it may make it apparent that you are not
running a Microsoft product).Before contacting your ISP, enable async logging locally
and wait until the connection hangs again. This may use up
quite a bit of disk space. The last data read from the port
may be of interest. It is usually ascii data, and may even
describe the problem
(Memory fault, core dumped?).If your ISP is helpful, they should be able to enable
logging on their end, then when the next link drop occurs,
they may be able to tell you why their side is having a
problem. Feel free to send the details to &a.brian;, or
even to ask your ISP to contact me directly.&man.ppp.8; has hung. What can I do?Your best bet here is to rebuild ppp by adding
CFLAGS+=-g and STRIP=
to the end of the Makefile, then doing a
make clean && make && make
install. When ppp hangs, find the ppp process id
with ps ajxww | fgrep ppp and run
gdb ppp PID.
From the gdb prompt, you can then use bt
to get a stack trace.Send the results to brian@Awfulhak.org.Why does nothing happen after the Login OK!
message?Prior to FreeBSD version 2.2.5, once the link was
established, &man.ppp.8;
would wait for the peer to initiate the Line Control Protocol
(LCP). Many ISPs will not initiate negotiations and expect
the client to do so. To force
ppp to initiate the LCP, use the
following line:set openmode activeIt usually does no
harm if both sides initiate negotiation, so openmode is now
active by default. However, the next section explains when
it does do some harm.I keep seeing errors about magic being the same. What does
it mean?Occasionally, just after connecting, you may see messages
in the log that say magic is the same.
Sometimes, these messages are harmless, and sometimes one side
or the other exits. Most ppp implementations cannot survive
this problem, and even if the link seems to come up, you will see
repeated configure requests and configure acknowledgments in
the log file until ppp eventually gives up and closes the
connection.This normally happens on server machines with slow disks
that are spawning a getty on the port, and executing ppp from
a login script or program after login. I have also heard reports
of it happening consistently when using slirp. The reason is
that in the time taken between getty exiting and ppp starting,
the client-side ppp starts sending Line Control Protocol (LCP)
packets. Because ECHO is still switched on for the port on
the server, the client ppp sees these packets
reflect back.One part of the LCP negotiation is to establish a magic
number for each side of the link so that
reflections can be detected. The protocol says
that when the peer tries to negotiate the same magic number, a
NAK should be sent and a new magic number should be chosen.
During the period that the server port has ECHO turned on, the
client ppp sends LCP packets, sees the same magic in the
reflected packet and NAKs it. It also sees the NAK reflect
(which also means ppp must change its magic). This produces a
potentially enormous number of magic number changes, all of
which are happily piling into the server's tty buffer. As soon
as ppp starts on the server, it is flooded with magic number
changes and almost immediately decides it has tried enough to
negotiate LCP and gives up. Meanwhile, the client, who no
longer sees the reflections, becomes happy just in time to see
a hangup from the server.This can be avoided by allowing the peer to start
negotiating with the following line in your ppp.conf
file:set openmode passiveThis tells ppp to wait for the server to initiate LCP
negotiations. Some servers however may never initiate
negotiations. If this is the case, you can do something
like:set openmode active 3This tells ppp to be passive for 3 seconds, and then to
start sending LCP requests. If the peer starts sending
requests during this period, ppp will immediately respond
rather than waiting for the full 3 second period.LCP negotiations continue 'till the connection is
closed. What is wrong?There is currently an implementation mis-feature in
ppp where it does not associate
LCP, CCP & IPCP responses with their original requests. As
a result, if one ppp
implementation is more than 6 seconds slower than the other
side, the other side will send two additional LCP configuration
requests. This is fatal.Consider two implementations,
A and
B. A starts
sending LCP requests immediately after connecting and
B takes 7 seconds to start. When
B starts, A
has sent 3 LCP REQs. We are assuming the line has ECHO switched
off, otherwise we would see magic number problems as described in
the previous section. B sends a
REQ, then an ACK to the first of
A's REQs. This results in
A entering the OPENED
state and sending and ACK (the first) back to
B. In the meantime,
B sends back two more ACKs in response to
the two additional REQs sent by A
before B started up.
B then receives the first ACK from
A and enters the
OPENED state.
A receives the second ACK from
B and goes back to the
REQ-SENT state, sending another (forth) REQ
as per the RFC. It then receives the third ACK and enters the
OPENED state. In the meantime,
B receives the forth REQ from
A, resulting in it reverting to the
ACK-SENT state and sending
another (second) REQ and (forth) ACK as per the RFC.
A gets the REQ, goes into
REQ-SENT and sends another REQ. It
immediately receives the following ACK and enters
OPENED.This goes on 'till one side figures out that they are
getting nowhere and gives up.The best way to avoid this is to configure one side to be
passive - that is, make one side
wait for the other to start negotiating. This can be done
with theset openmode passivecommand. Care should be taken with this option. You
should also use theset stopped Ncommand to limit the amount of time that
ppp waits for the peer to begin
negotiations. Alternatively, theset openmode active Ncommand (where N is the
number of seconds to wait before starting negotiations) can be
used. Check the manual page for details.Why does &man.ppp.8; lock up shortly after connection?Prior to version 2.2.5 of FreeBSD, it was possible that
your link was disabled shortly after connection due to
ppp mis-handling Predictor1
compression negotiation. This would only happen if both sides
tried to negotiate different Compression Control Protocols
(CCP). This problem is now corrected, but if you are still
running an old version of ppp,
the problem can be circumvented with the linedisable pred1Why does &man.ppp.8; lock up when I shell out to test it?When you execute the shell or
! command, ppp executes a
shell (or if you have passed any arguments,
ppp will execute those arguments). Ppp will
wait for the command to complete before continuing. If you
attempt to use the ppp link while running the command, the link
will appear to have frozen. This is because
ppp is waiting for the command to
complete.If you wish to execute commands like this, use the
!bg command instead. This will execute
the given command in the background, and ppp can continue to
service the link.How come &man.ppp.8; over a null-modem cable never exits?There is no way for ppp to
automatically determine that a direct connection has been
dropped. This is due to the lines that are used in a
null-modem serial cable. When using this sort of connection,
LQR should always be enabled with the lineenable lqrLQR is accepted by default if negotiated by the peer.Why does &man.ppp.8; dial for no reason in -auto mode?If ppp is dialing
unexpectedly, you must determine the cause, and set up Dial
filters (dfilters) to prevent such dialing.To determine the cause, use the following line:set log +tcp/ipThis will log all traffic through the connection. The
next time the line comes up unexpectedly, you will see the
reason logged with a convenient timestamp next to it.You can now disable dialing under these circumstances.
Usually, this sort of problem arises due to DNS lookups. To
prevent DNS lookups from establishing a connection (this will
not prevent
ppp from passing the packets
through an established connection), use the following:set dfilter 1 deny udp src eq 53
set dfilter 2 deny udp dst eq 53
set dfilter 3 permit 0/0 0/0This is not always suitable, as it will effectively break
your demand-dial capabilities - most programs will need a DNS
lookup before doing any other network related things.In the DNS case, you should try to determine what is
actually trying to resolve a host name. A lot of the time,
&man.sendmail.8; is the culprit. You should make sure that
you tell sendmail not to do any DNS lookups in its
configuration file. See the section on
Mail Configuration for details
on how to create your own configuration file and what should
go into it. You may also want to add the following line to
your .mc file:define(`confDELIVERY_MODE', `d')dnlThis will make sendmail queue everything until the queue
is run (usually, sendmail is invoked with
, telling it to run the queue every
30 minutes) or until a sendmail -q is done
(perhaps from your ppp.linkup file).What do these CCP errors mean?I keep seeing the following errors in my log file:CCP: CcpSendConfigReq
CCP: Received Terminate Ack (1) state = Req-Sent (6)This is because ppp is trying to negotiate Predictor1
compression, and the peer does not want to negotiate any
compression at all. The messages are harmless, but if you
wish to remove them, you can disable Predictor1 compression
locally too:disable pred1Why does &man.ppp.8; lock up during file transfers with IO
errors?Under FreeBSD 2.2.2 and before, there was a bug in the
tun driver that prevents incoming packets of a size larger
than the tun interface's MTU size. Receipt of a packet
greater than the MTU size results in an IO error being logged
via syslogd.The ppp specification says that an MRU of 1500 should
always be accepted as a minimum,
despite any LCP negotiations, therefore it is possible that
should you decrease the MTU to less than 1500, your ISP will
transmit packets of 1500 regardless, and you will tickle this
non-feature - locking up your link.The problem can be circumvented by never setting an MTU of
less than 1500 under FreeBSD 2.2.2 or before.Why doesn't &man.ppp.8; log my connection speed?In order to log all lines of your modem
conversation, you must enable the
following:set log +connectThis will make &man.ppp.8; log
everything up until the last requested expect
string.If you wish to see your connect speed and are using PAP
or CHAP (and therefore do not have anything to
chat after the CONNECT in the dial script - no
set login script), you must make sure that
you instruct ppp to expect the whole CONNECT
line, something like this:set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \
\"\" ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT \\c \\n"Here, we get our CONNECT, send nothing, then expect a
line-feed, forcing ppp to read
the whole CONNECT response.Why does &man.ppp.8; ignore the \ character
in my chat script?Ppp parses each line in your config files so that it can
interpret strings such as
set phone "123 456 789" correctly (and
realize that the number is actually only
one argument. In order to specify
a " character, you must escape it using a
backslash (\).When the chat interpreter parses each argument, it
re-interprets the argument in order to find any special
escape sequences such as \P or
\T (see the man page). As a result of this
double-parsing, you must remember to use the correct number of
escapes.If you wish to actually send a \
character to (say) your modem, you would need something
like:set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK"resulting in the following sequence:ATZ
OK
AT\X
OKorset phone 1234567
set dial "\"\" ATZ OK ATDT\\T"resulting in the following sequence:ATZ
OK
ATDT1234567Why does &man.ppp.8; get a seg-fault, but I see no
ppp.core file?Ppp (or any other program for that matter) should never
dump core. Because ppp runs with an effective user id of 0,
the operating system will not write ppp's core image to disk
before terminating it. If, however ppp
is actually terminating due to a
segmentation violation or some other signal that normally
causes core to be dumped, and
you are sure you are using the latest version (see the start of
this section), then you should do the following:&prompt.user; tar xfz ppp-*.src.tar.gz
&prompt.user; cd ppp*/ppp
&prompt.user; echo STRIP= >>Makefile
&prompt.user; echo CFLAGS+=-g >>Makefile
&prompt.user; make clean all
&prompt.user; su
&prompt.root; make install
&prompt.root; chmod 555 /usr/sbin/pppYou will now have a debuggable version of ppp installed.
You will have to be root to run ppp as all of its privileges
have been revoked. When you start ppp, take a careful note
of what your current directory was at the time.Now, if and when ppp receives the segmentation violation,
it will dump a core file called ppp.core. You should then do
the following:&prompt.user; su
&prompt.root; gdb /usr/sbin/ppp ppp.core(gdb)bt
.....
(gdb)f 0
....
(gdb)i args
....
(gdb)l
.....All of this information should be given alongside your
question, making it possible to diagnose the problem.If you are familiar with gdb, you may wish to find out some
other bits and pieces such as what actually caused the dump and
the addresses & values of the relevant variables.Why does the process that forces a dial in auto mode never
connect?This was a known problem with
ppp set up to negotiate a
dynamic local IP number with the peer in auto mode. It is
fixed in the latest version - search the man page for
iface.The problem was that when that initial program calls
&man.connect.2;, the IP number of the tun interface is assigned
to the socket endpoint. The kernel creates the first outgoing
packet and writes it to the tun device.
ppp then reads the packet and
establishes a connection. If, as a result of
ppp's dynamic IP assignment, the
interface address is changed, the original socket endpoint will
be invalid. Any subsequent packets sent to the peer will
usually be dropped. Even if they are not, any responses will
not route back to the originating machine as the IP number is
no longer owned by that machine.There are several theoretical ways to approach this
problem. It would be nicest if the peer would re-assign the
same IP number if possible :-)
The current version of ppp does
this, but most other implementations do not.The easiest method from our side would be to never change
the tun interface IP number, but instead to change all outgoing
packets so that the source IP number is changed from the
interface IP to the negotiated IP on the fly. This is
essentially what the iface-alias option in
the latest version of ppp is
doing (with the help of
&man.libalias.3; and ppp's switch) -
it is maintaining all previous interface addresses and NATing
them to the last negotiated address.Another alternative (and probably the most reliable) would
be to implement a system call that changes all bound sockets
from one IP to another. ppp would
use this call to modify the sockets of all existing programs
when a new IP number is negotiated. The same system call could
be used by dhcp clients when they are forced to re-bind() their
sockets.Yet another possibility is to allow an interface to be
brought up without an IP number. Outgoing packets would be
given an IP number of 255.255.255.255 up until the first
SIOCAIFADDR ioctl is done. This would result in fully binding
the socket. It would be up to ppp
to change the source IP number, but only if it is set to
255.255.255.255, and only the IP number and IP checksum would
need to change. This, however is a bit of a hack as the kernel
would be sending bad packets to an improperly configured
interface, on the assumption that some other mechanism is
capable of fixing things retrospectively.Why don't most games work with the -nat switch?The reason games and the like do not work when libalias
is in use is that the machine on the outside will try to open a
connection or send (unsolicited) UDP packets to the machine on
the inside. The NAT software does not know that it should send
these packets to the interior machine.To make things work, make sure that the only thing
running is the software that you are having problems with, then
either run tcpdump on the tun interface of the gateway or
enable ppp tcp/ip logging (set log +tcp/ip)
on the gateway.When you start the offending software, you should see
packets passing through the gateway machine. When something
comes back from the outside, it will be dropped (that is the
problem). Note the port number of these packets then shut down
the offending software. Do this a few times to see if the port
numbers are consistent. If they are, then the following line in
the relevant section of /etc/ppp/ppp.conf will make the
software functional:nat port protointernalmachine:portportwhere proto is either
tcp or udp,
internalmachine is the machine that
you want the packets to be sent to and
port is the destination port number
of the packets.You will not be able to use the software on other machines
without changing the above command, and running the software
on two internal machines at the same time is out of the question
- after all, the outside world is seeing your entire internal
network as being just a single machine.If the port numbers are not consistent, there are three
more options:Submit support in
libalias. Examples of special cases can be found
in /usr/src/lib/libalias/alias_*.c
(alias_ftp.c is a good prototype). This
usually involves reading certain recognised outgoing packets,
identifying the instruction that tells the outside machine to
initiate a connection back to the internal machine on a
specific (random) port and setting up a route in
the alias table so that the subsequent packets know where to
go.This is the most difficult solution, but it is the best
and will make the software work with multiple machines.Use a proxy. The
application may support socks5 for example, or (as in the
cvsup case) may have a passive
option that avoids ever requesting that the peer open
connections back to the local machine.Redirect everything to
the internal machine using nat addr. This
is the sledge-hammer approach.Has anybody made a list of useful port numbers?Not yet, but this is intended to grow into such a list
(if any interest is shown). In each example,
internal should be replaced with
the IP number of the machine playing the game.Asheron's Callnat port udp
internal
:65000 65000Manually change the port number within the game to
65000. If you have got a number of machines that you wish
to play on assign a unique port number for each (i.e.
65001, 65002, etc) and add a nat port
line for each one.Half Lifenat port udp
internal:27005
27015PCAnywhere 8.0nat port udp
internal:5632
5632nat port tcp
internal:5631
5631Quakenat port udp
internal:6112
6112Alternatively, you may want to take a look at
www.battle.net for Quake proxy support.Quake 2nat port udp
internal:27901
27910nat port udp
internal:60021
60021nat port udp
internal:60040
60040Red Alertnat port udp
internal:8675
8675nat port udp
internal:5009
5009What are FCS errors?FCS stands for Frame
Check
Sequence. Each ppp packet
has a checksum attached to ensure that the data being
received is the data being sent. If the FCS of an incoming
packet is incorrect, the packet is dropped and the HDLC FCS
count is increased. The HDLC error values can be displayed
using the show hdlc command.If your link is bad (or if your serial driver is dropping
packets), you will see the occasional FCS error. This is not
usually worth worrying about although it does slow down the
compression protocols substantially. If you have an external
modem, make sure your cable is properly shielded from
interference - this may eradicate the problem.If your link freezes as soon as you have connected and you
see a large number of FCS errors, this may be because your link
is not 8 bit clean. Make sure your modem is not using software
flow control (XON/XOFF). If your datalink
must use software flow control, use the
command set accmap 0x000a0000 to tell
ppp to escape the ^Q and
^S characters.Another reason for seeing too many FCS errors may be that
the remote end has stopped talking PPP. You
may want to enable async logging at this
point to determine if the incoming data is actually a login or
shell prompt. If you have a shell prompt at the remote end,
it is possible to terminate ppp without dropping the line by
using the close lcp command (a following
term command will reconnect you to the shell
on the remote machine.If nothing in your log file indicates why the link might
have been terminated, you should ask the remote administrator
(your ISP?) why the session was terminated.Why do MacOS and Windows 98 connections freeze when
running PPPoE on the gateway?Thanks to Michael Wozniak
mwozniak@netcom.ca for figuring this out and
Dan Flemming danflemming@mac.com for the Mac
solution:This is due to what is called a Black Hole
router. MacOS and Windows 98 (and maybe other Microsoft OSs)
send TCP packets with a requested segment size too big to fit
into a PPPoE frame (MTU is 1500 by default for Ethernet)
and have the do not
fragment bit set (default of TCP) and the Telco router
is not sending ICMP must fragment back to the
www site you are trying to load. (Alternatively, the router is
sending the ICMP packet correctly, but the firewall at the www
site is dropping it.) When the www server is sending
you frames that do not fit into the PPPoE pipe the Telco router
drops them on the floor and your page does not load (some
pages/graphics do as they are smaller than a MSS.) This seems
to be the default of most Telco PPPoE configurations (if only
they knew how to program a router... sigh...)One fix is to use regedit on your 95/98 boxes to add the
following registry entry...HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\0000\MaxMTUIt should be a string with a value 1436, as
some ADSL routers are reported to be unable to deal with packets
larger than this. This registry key has been changed to
Tcpip\Parameters\Interfaces\ID for adapter\MTU
in Windows 2000 and becomes a DWORD.Refer to the Microsoft Knowledge Base documents Q158474
- Windows TCPIP Registry Entries and Q120642
- TCPIP & NBT Configuration Parameters for Windows
NT for more information on changing Windows MTU to
work with a NAT router.Another regedit possibility under Windows 2000 is to
set the
Tcpip\Parameters\Interfaces\ID for
adapter\EnablePMTUBHDetect DWORD
to 1 as mentioned in the Microsoft document 120642
mentioned above.Unfortunately, MacOS does not provide an interface for
changing TCP/IP settings. However, there is commercial software
available, such as OTAdvancedTuner (OT for OpenTransport, the
MacOS TCP/IP stack) by Sustainable Softworks,
that will allow users to customize TCP/IP settings. MacOS NAT
users should select ip_interface_MTU from
the drop-down menu, enter 1450 instead of
1500 in the box, click the box next to
Save as Auto Configure, and click
Make Active.The latest version of ppp
(2.3 or greater) has an enable tcpmssfixup
command that will automatically adjust the MSS to an appropriate
value. This facility is enabled by default. If you are stuck
with an older version of ppp, you
may want to look at the tcpmssd
port.None of this helps - I am desperate! What can I do?If all else fails, send as much information as you can,
including your config files, how you are starting
ppp, the relevant parts of your
log file and the output of the netstat -rn
command (before and after connecting) to the &a.questions; or
the
comp.unix.bsd.freebsd.misc news group, and someone
should point you in the right direction.Serial CommunicationsThis section answers common questions about serial
communications with FreeBSD. PPP and SLIP are covered in the
section.How do I tell if FreeBSD found my serial ports?As the FreeBSD kernel boots, it will probe for the serial
ports in your system for which the kernel was configured.
You can either watch your system closely for the messages it
prints or run the command&prompt.user; dmesg | grep sioafter your system is up and running.Here is some example output from the above command:sio0 at 0x3f8-0x3ff irq 4 on isa
sio0: type 16550A
sio1 at 0x2f8-0x2ff irq 3 on isa
sio1: type 16550AThis shows two serial ports. The first is on irq 4, is
using port address 0x3f8, and has a
16550A-type UART chip. The second uses the same kind of chip
but is on irq 3 and is at port address 0x2f8.
Internal modem cards are treated just like serial ports---except
that they always have a modem attached to the
port.The GENERIC kernel includes support
for two serial ports using the same irq and port address
settings in the above example. If these settings are not
right for your system, or if you've added modem cards or have
more serial ports than your kernel is configured for, just
reconfigure your kernel. See section
about building a kernel for
more details.How do I tell if FreeBSD found my modem cards?Refer to the answer to the previous question.I just upgraded to 2.0.5 and my
tty0X
are missing! How do I solve this problem?Do not worry, they have been merged with the
ttydX devices. You will have to change
any old configuration files you have, though.How do I access the serial ports on FreeBSD?The third serial port,
sio2
(see &man.sio.4;, known as COM3 in DOS), is on /dev/cuaa2
for dial-out devices, and on /dev/ttyd2
for dial-in devices. What is the difference between these two
classes of devices?You use ttydX for dial-ins. When
opening /dev/ttydX in blocking mode, a
process will wait for the corresponding
cuaaX device to become inactive, and then
wait for the carrier detect line to go active. When you open
the cuaaX device, it makes sure the serial
port is not already in use by the ttydX
device. If the port is available, it steals it
from the ttydX device. Also, the
cuaaX device does not care about carrier
detect. With this scheme and an auto-answer modem, you can have
remote users log in and you can still dialout with the same
modem and the system will take care of all the
conflicts.How do I enable support for a multiport serial
card?Again, the section on kernel configuration provides
information about configuring your kernel. For a multiport
serial card, place an &man.sio.4; line
for each serial port on the card in the kernel configuration
file. But place the irq and vector specifiers on only one of
the entries. All of the ports on the card should share one irq.
For consistency, use the last serial port to specify the irq.
Also, specify the COM_MULTIPORT
option.The following example is for an AST 4-port serial card on
irq 7:options "COM_MULTIPORT"
device sio4 at isa? port 0x2a0 tty flags 0x781
device sio5 at isa? port 0x2a8 tty flags 0x781
device sio6 at isa? port 0x2b0 tty flags 0x781
device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointrThe flags indicate that the master port has minor number 7
(0x700), diagnostics enabled during probe
(0x080), and all the ports share an irq
(0x001).Can FreeBSD handle multiport serial cards sharing
irqs?Not yet. You will have to use a different irq for each
card.Can I set the default serial parameters for a
port?The ttydX (or
cuaaX) device is the regular device
you will want to open for your applications. When a process
opens the device, it will have a default set of terminal I/O
settings. You can see these settings with the command&prompt.root; stty -a -f /dev/ttyd1When you change the settings to this device, the settings
are in effect until the device is closed. When it is reopened,
it goes back to the default set. To make changes to the
default set, you can open and adjust the settings of the
initial state device. For example, to turn on
CLOCAL mode, 8 bits, and
XON/XOFF flow control by default for
ttyd5, do:&prompt.root; stty -f /dev/ttyid5 clocal cs8 ixon ixoffA good place to do this is in
/etc/rc.serial. Now, an application will
have these settings by default when it opens
ttyd5. It can still change these settings
to its liking, though.You can also prevent certain settings from being changed
by an application by making adjustments to the
lock state device. For example, to lock the
speed of ttyd5 to 57600 bps, do&prompt.root; stty -f /dev/ttyld5 57600Now, an application that opens ttyd5
and tries to change the speed of the port will be stuck with
57600 bps.Naturally, you should make the initial state and lock state
devices writable only by root. The
&man.MAKEDEV.8;
script does NOT do this when it creates the
device entries.How can I enable dialup logins on my modem?So you want to become an Internet service provider, eh?
First, you will need one or more modems that can auto-answer.
Your modem will need to assert carrier-detect when it detects a
carrier and not assert it all the time. It will need to hang up
the phone and reset itself when the data terminal ready
(DTR) line goes from on to off. It should
probably use RTS/CTS flow control or no
local flow control at all. Finally, it must use a constant
speed between the computer and itself, but (to be nice to your
callers) it should negotiate a speed between itself and the
remote modem.For many Hayes command-set--compatible modems, this
command will make these settings and store them in
nonvolatile memory:AT &C1 &D3 &K3 &Q6 S0=1 &WSee the section on sending AT
commands below for information on how to make these
settings without resorting to an MS-DOS terminal program.Next, make an entry in
/etc/ttys (see &man.ttys.5;) for the modem. This file lists all the ports
on which the operating system will await logins. Add a line
that looks something like this:ttyd1 "/usr/libexec/getty std.57600" dialup on insecureThis line indicates that the second serial port
(/dev/ttyd1) has a modem connected
running at 57600 bps and no parity
(std.57600, which comes from the file
/etc/gettytab, see &man.gettytab.5;).
The terminal type for this port is dialup.
The port is on and is
insecure---meaning root logins on the port
are not allowed. For dialin ports like this one, use the
ttydX entry.It is common practice to use dialup as
the terminal type. Many users set up in their .profile or
.login files a prompt for the actual terminal type if the
starting type is dialup. The example shows the port as
insecure. To become root on this port, you have to login as a
regular user, then &man.su.1; to become
root. If you use secure
then root can login in directly.After making modifications to
/etc/ttys, you need to send a hangup or
HUP signal to the
&man.init.8; process:&prompt.root; kill -HUP 1This forces the &man.init.8; process to reread
/etc/ttys. The init process will then start getty
processes on all on ports. You can find
out if logins are available for your port by typing&prompt.user; ps -ax | grep '[t]tyd1'You should see something like:747 ?? I 0:00.04 /usr/libexec/getty std.57600 ttyd1How can I connect a dumb terminal to my FreeBSD
box?If you are using another computer as a terminal into your
FreeBSD system, get a null modem cable to go between the two
serial ports. If you are using an actual terminal, see its
accompanying instructions.Then, modify
/etc/ttys (see &man.ttys.5;), like above. For example, if you are
hooking up a WYSE-50 terminal to the fifth serial port,
use an entry like this:ttyd4 "/usr/libexec/getty std.38400" wyse50 on secureThis example shows that the port on
/dev/ttyd4 has a wyse50 terminal
connected at 38400 bps with no parity
(std.38400 from
/etc/gettytab, see &man.gettytab.5;) and root logins are
allowed (secure).Why can't I run tip or
cu?On your system, the programs &man.tip.1;
and &man.cu.1;
are probably executable only by
uucp
and group dialer. You can use the group
dialer to control who has access to your
modem or remote systems. Just add yourself to group
dialer.Alternatively, you can let everyone on your system
run &man.tip.1; and &man.cu.1; by
typing:&prompt.root; chmod 4511 /usr/bin/cu
&prompt.root; chmod 4511 /usr/bin/tipMy stock Hayes modem is not supported---what
can I do?Actually, the man page for &man.tip.1; is
out of date. There is a generic Hayes dialer already built in.
Just use at=hayes in your
/etc/remote (see &man.remote.5;) file.The Hayes driver is not smart enough to recognize some of
the advanced features of newer modems---messages like
BUSY, NO DIALTONE, or
CONNECT 115200 will just confuse it. You
should turn those messages off when you use &man.tip.1;
(using ATX0&W).Also, the dial timeout for &man.tip.1; is 60
seconds. Your modem should use something less, or else tip
will think there is a communication problem. Try
ATS7=45&W.Actually, as shipped &man.tip.1; does not yet
support it fully. The solution is to edit the file
tipconf.h in the directory
/usr/src/usr.bin/tip/tip. Obviously you
need the source distribution to do this.Edit the line #define HAYES 0
to #define HAYES 1. Then
make and make install.
Everything works nicely after that.How am I expected to enter these AT commands?Make what is called a direct entry in your
/etc/remote file (see &man.remote.5;). For example, if your modem is hooked
up to the first serial port, /dev/cuaa0,
then put in the following line:cuaa0:dv=/dev/cuaa0:br#19200:pa=noneUse the highest bps rate your modem supports in the br
capability. Then, type
tip cuaa0 (see &man.tip.1;)
and you will be connected to your modem.If there is no /dev/cuaa0 on your
system, do this:&prompt.root; cd /dev
&prompt.root; sh MAKEDEV cuaa0Or use cu as root with the following command:&prompt.root; cu -lline -sspeedwith line being the serial port (e.g.
/dev/cuaa0) and speed being the speed
(e.g.57600). When you are done entering
the AT commands hit ~. to exit.How come the <@> sign for the pn
capability does not work?The <@> sign in the phone number
capability tells tip to look in
/etc/phones for a phone number. But the
<@> sign is also a special character
in capability files like /etc/remote.
Escape it with a backslash:pn=\@How can I dial a phone number on the command
line?Put what is called a generic entry in your
/etc/remote file (see &man.remote.5;). For example:tip115200|Dial any phone number at 115200 bps:\
:dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du:
tip57600|Dial any phone number at 57600 bps:\
:dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:Then you can do something like tip -115200
5551234. If you prefer &man.cu.1;
over
&man.tip.1;, use a generic cu entry:cu115200|Use cu to dial any number at 115200bps:\
:dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:and type cu 5551234 -s 115200.Do I have to type in the bps rate every time I do
that?Put in an entry for tip1200 or
cu1200, but go ahead and use whatever bps
rate is appropriate with the br capability.
&man.tip.1;
thinks a good default is 1200 bps which is why it looks for
a tip1200 entry. You do not have to use 1200
bps, though.How can I more easily access a number of hosts through a
terminal server?Rather than waiting until you are connected and typing
CONNECT host
each time, use tip's cm capability. For
example, these entries in
/etc/remote (see &man.remote.5;):pain|pain.deep13.com|Forrester's machine:\
:cm=CONNECT pain\n:tc=deep13:
muffin|muffin.deep13.com|Frank's machine:\
:cm=CONNECT muffin\n:tc=deep13:
deep13:Gizmonics Institute terminal server:\
:dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234:will let you type tip pain or
tip muffin to connect to the hosts
pain or muffin; and
tip deep13 to get to the terminal
server.Can tip try more than one line for each site?This is often a problem where a university has several
modem lines and several thousand students trying to use
them...Make an entry for your university in
/etc/remote (see &man.remote.5;) and use <\@> for
the pn capability:big-university:\
:pn=\@:tc=dialout
dialout:\
:dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:Then, list the phone numbers for the university in
/etc/phones (see &man.phones.5;):big-university 5551111
big-university 5551112
big-university 5551113
big-university 5551114&man.tip.1;
will try each one in the listed order, then give
up. If you want to keep retrying, run &man.tip.1;
in a while loop.Why do I have to hit CTRL+P twice to send CTRL+P
once?CTRL+P is the default force character,
used to tell &man.tip.1;
that the next character is literal data. You can set the
force character to any other character with the
~s escape, which means set a
variable.Type ~sforce=single-char
followed by a newline.
single-char is any single character.
If you leave out single-char,
then the force character is the nul character, which you can
get by typing CTRL+2 or CTRL+SPACE. A pretty good value for
single-char is SHIFT+CTRL+6, which
I have seen only used on some terminal servers.You can have the force character be whatever you want by
specifying the following in your
$HOME/.tiprc file:force=single-charWhy is everything I type suddenly in UPPER CASE?You must have pressed CTRL+A, &man.tip.1;
raise character, specially
designed for people with broken caps-lock keys. Use
~s as above and set the variable
raisechar to something reasonable. In fact,
you can set it to the same as the force character, if you
never expect to use either of these features.Here is a sample .tiprc file perfect for Emacs users who
need to type CTRL+2 and CTRL+A a lot:force=^^
raisechar=^^The ^^ is SHIFT+CTRL+6.How can I do file transfers with
tip?If you are talking to another Unix system, you can send
and receive files with ~p (put) and
~t (take). These commands run
&man.cat.1; and
&man.echo.1; on the remote system to accept and send files.
The syntax is:~p <local-file> [<remote-file>]
~t <remote-file> [<local-file>]There is no error checking, so you probably should use
another protocol, like zmodem.How can I run zmodem with
tip?First, install one of the zmodem programs from the
ports collection (such as one of the two from the comms
category, lrzsz or
rzsz.To receive files, start the sending program on the
remote end. Then, press enter and type
~C rz (or ~C lrz if you
installed lrzsz) to begin
receiving them locally.To send files, start the receiving program on the remote
end. Then, press enter and type
~C sz files
(or ~C lsz files)
to send them to the remote system.How come FreeBSD cannot seem to find my serial ports, even
when the settings are correct?Motherboards and cards with Acer UARTs do not probe
properly under the FreeBSD sio probe. Obtain a patch from
www.lemis.com to fix your problem.Miscellaneous QuestionsFreeBSD uses far more swap space than Linux. Why?FreeBSD only appears to use more swap than Linux. In
actual fact, it does not. The main difference between FreeBSD
and Linux in this regard is that FreeBSD will proactively move
entirely idle, unused pages of main memory into swap in order
to make more main memory available for active use. Linux tends
to only move pages to swap as a last resort. The perceived
heavier use of swap is balanced by the more efficient use of
main memory.Note that while FreeBSD is proactive in this regard, it
does not arbitrarily decide to swap pages when the system is
truly idle. Thus you will not find your system all paged
out when you get up in the morning after leaving it idle
overnight.Why does top show very little free memory even
when I have very few programs running?The simple answer is that free memory is wasted
memory. Any memory that your programs do not actively
allocate is used within the FreeBSD kernel as disk
cache. The values shown by &man.top.1; labelled as
Inact, Cache, and
Buf are all cached data at different
aging levels. This cached data means the system does
not have to access a slow disk again for data it has
accessed recently, thus increasing overall performance.
In general, a low value shown for Free
memory in &man.top.1; is good, provided it is not
very low.Why use (what are) a.out and ELF executable
formats?To understand why FreeBSD uses the
ELF format, you must first know a little
about the 3 currently dominant executable
formats for Unix:Prior to FreeBSD 3.x, FreeBSD used the a.out
format.&man.a.out.5;The oldest and classic unix object
format. It uses a short and compact header with a magic
number at the beginning that is often used to
characterize the format (see
&man.a.out.5; for more details). It contains three
loaded segments: .text, .data, and .bss plus a symbol
table and a string table.COFFThe SVR3 object format. The header now comprises
a section table, so you can have more than just .text,
.data, and .bss sections.ELFThe successor to COFF, featuring
Multiple sections and 32-bit or 64-bit possible values.
One major drawback: ELF was also
designed with the assumption that there would be only
one ABI per system architecture. That assumption is
actually quite incorrect, and not even in the
commercial SYSV world (which has at least three ABIs:
SVR4, Solaris, SCO) does it hold true.FreeBSD tries to work around this problem somewhat
by providing a utility for branding
a known ELF executable with
information about the ABI it is compliant with. See the
man page for &man.brandelf.1;
for more information.FreeBSD comes from the classic camp and has
traditionally used the &man.a.out.5;
format, a technology tried and proven through
many generations of BSD releases. Though it has also been
possible for some time to build and run native
ELF binaries (and kernels) on a FreeBSD
system, FreeBSD initially resisted the push to
switch to ELF as the default format. Why?
Well, when the Linux camp made their painful transition to
ELF, it was not so much to flee the
a.out executable format as it was their
inflexible jump-table based shared library mechanism, which
made the construction of shared libraries very difficult for
vendors and developers alike. Since the ELF
tools available offered a solution to the shared library
problem and were generally seen as the way
forward anyway, the migration cost was accepted as
necessary and the transition made.In FreeBSD's case, our shared library mechanism is based
more closely on Sun's SunOS-style
shared library mechanism and, as such, is very easy to use.
However, starting with 3.0, FreeBSD officially supports
ELF binaries as the default format. Even
though the a.out executable format has
served us well, the GNU people, who author the compiler tools
we use, have dropped support for the a.out
format. This has forced us to maintain a divergent version of
the compiler and linker, and has kept us from reaping the
benefits of the latest GNU development efforts. Also the
demands of ISO-C++, notably constructors and destructors, has
also led to native ELF support in future
FreeBSD releases.Yes, but why are there so many different formats?Back in the dim, dark past, there was simple hardware.
This simple hardware supported a simple, small system. a.out
was completely adequate for the job of representing binaries on
this simple system (a PDP-11). As people ported Unix from this
simple system, they retained the a.out format because it was
sufficient for the early ports of Unix to architectures like
the Motorola 68k, VAXen, etc.Then some bright hardware engineer decided that if he
could force software to do some sleazy tricks, then he would be
able to shave a few gates off the design and allow his CPU core
to run faster. While it was made to work with this new kind of
hardware (known these days as RISC), a.out
was ill-suited for this hardware, so many formats were
developed to get to a better performance from this hardware
than the limited, simple a.out format
could offer. Things like COFF,
ECOFF, and a few obscure others were
invented and their limitations explored before things seemed to
settle on ELF.In addition, program sizes were getting huge and disks
(and physical memory) were still relatively small so the
concept of a shared library was born. The VM system also became
more sophisticated. While each one of these advancements was
done using the a.out format, its
usefulness was stretched more and more with each new feature.
In addition, people wanted to dynamically load things at run
time, or to junk parts of their program after the init code had
run to save in core memory and/or swap space. Languages became
more sophisticated and people wanted code called before main
automatically. Lots of hacks were done to the
a.out format to allow all of these things
to happen, and they basically worked for a time. In time,
a.out was not up to handling all these
problems without an ever increasing overhead in code and
complexity. While ELF solved many of these
problems, it would be painful to switch from the system that
basically worked. So ELF had to wait until
it was more painful to remain with a.out
than it was to migrate to ELF.However, as time passed, the build tools that FreeBSD
derived their build tools from (the assembler and loader
especially) evolved in two parallel trees. The FreeBSD tree
added shared libraries and fixed some bugs. The GNU folks that
originally write these programs rewrote them and added simpler
support for building cross compilers, plugging in different
formats at will, etc. Since many people wanted to build cross
compilers targeting FreeBSD, they were out of luck since the
older sources that FreeBSD had for as and ld were not up to the
task. The new gnu tools chain (binutils) does support cross
compiling, ELF, shared libraries, C++
extensions, etc. In addition, many vendors are releasing
ELF binaries, and it is a good thing for
FreeBSD to run them. And if it is running
ELF binaries, why bother having
a.out any more? It is a tired old horse
that has proven useful for a long time, but it is time to turn
him out to pasture for his long, faithful years of
service.ELF is more expressive than a.out and
will allow more extensibility in the base system. The
ELF tools are better maintained, and offer
cross compilation support, which is important to many people.
ELF may be a little slower than a.out, but
trying to measure it can be difficult. There are also numerous
details that are different between the two in how they map
pages, handle init code, etc. None of these are very important,
but they are differences. In time support for
a.out will be moved out of the GENERIC
kernel, and eventually removed from the kernel once the need to
run legacy a.out programs is past.Why won't chmod change the permissions on symlinks?Symlinks do not have permissions, and by default,
&man.chmod.1; will not follow symlinks to change the
permissions on the target file. So if you have a file,
foo, and a symlink to that file,
bar, then this command will always
succeed.&prompt.user; chmod g-w barHowever, the permissions on foo will
not have changed.You have to use either or
together with the
option to make this work. See the
&man.chmod.1; and &man.symlink.7;
man pages for more info.The option does a
RECURSIVE
&man.chmod.1;. Be careful about
specifying directories or symlinks to directories to
&man.chmod.1;. If you want to
change the permissions of a directory referenced by a
symlink, use &man.chmod.1;
without any options and follow the symlink
with a trailing slash (/). For
example, if foo is a symlink to
directory bar, and you want to change
the permissions of foo (actually
bar), you would do something
like:&prompt.user; chmod 555 foo/With the trailing slash, &man.chmod.1;
will follow the symlink,
foo, to change the permissions of the
directory, bar.Why are login names still
restricted to 8 characters?You would think it would be easy enough to change
UT_NAMESIZE and rebuild the whole world,
and everything would just work. Unfortunately there are often
scads of applications and utilities (including system tools)
that have hard-coded small numbers (not always
8 or 9, but oddball ones
like 15 and 20) in
structures and buffers. Not only will this get you log files
which are trashed (due to variable-length records getting
written when fixed records were expected), but it can break
Suns NIS clients and potentially cause other problems in
interacting with other Unix systems.In FreeBSD 3.0 and later, the maximum name length has
been increased to 16 characters and those various utilities
with hard-coded name sizes have been found and fixed. The fact
that this touched so many areas of the system is why, in fact,
the change was not made until 3.0.If you are absolutely confident in your ability to find
and fix these sorts of problems for yourself when and if they
pop up, you can increase the login name length in earlier
releases by editing /usr/include/utmp.h and changing
UT_NAMESIZE accordingly. You must also update MAXLOGNAME in
/usr/include/sys/param.h to match the UT_NAMESIZE change.
Finally, if you build from sources, do not forget that
/usr/include is updated each time! Change the appropriate files
in /usr/src/.. instead.Can I run DOS binaries under FreeBSD?Yes, starting with version 3.0 you can using BSDI's
doscmd DOS emulation which has
been integrated and enhanced. Send mail to the &a.emulation;
if you are interested in joining this ongoing effort!For pre-3.0 systems, there is a neat utility called
pcemu in the ports collection which emulates an 8088
and enough BIOS services to run DOS text mode applications.
It requires the X Window System (provided as XFree86).What do I need to do to translate a FreeBSD document into
my native language?See the
Translation FAQ in the FreeBSD Documentation Project
Primer.Where can I find a free FreeBSD account?While FreeBSD does not provide open access to any of their
servers, others do provide open access Unix systems. The
charge varies and limited services may be available.Arbornet,
Inc, also known as M-Net, has been providing open
access to Unix systems since 1983. Starting on an Altos
running System III, the site switched to BSD/OS in 1991. In
June of 2000, the site switched again to FreeBSD. M-Net can be
accessed via telnet and SSH and provides basic access to the
entire FreeBSD software suite. However, network access is
limited to members and patrons who donate to the system, which
is run as a non-profit organization. M-Net also provides an
bulletin board system and interactive chat.Grex provides a
site very similar to M-Net including the same bulletin board
and interactive chat software. However, the machine is a Sun
4M and is running SunOSWhat is sup, and how do I use
it?
SUP stands for Software Update Protocol, and was
developed by CMU for keeping their development trees in sync.
We used it to keep remote sites in sync with our central
development sources.SUP is not bandwidth friendly, and has been retired.
The current recommended method to keep your sources up to
date is
Handbook entry on CVSupHow cool is FreeBSD?Q. Has anyone done any temperature testing while
running FreeBSD? I know Linux runs cooler than dos, but have
never seen a mention of FreeBSD. It seems to run really
hot.A. No, but we have done numerous taste tests on
blindfolded volunteers who have also had 250 micrograms of
LSD-25 administered beforehand. 35% of the volunteers said that
FreeBSD tasted sort of orange, whereas Linux tasted like purple
haze. Neither group mentioned any significant variances in
temperature. We eventually had to throw the
results of this survey out entirely anyway when we found that
too many volunteers were wandering out of the room during the
tests, thus skewing the results. We think most of the volunteers
are at Apple now, working on their new scratch and
sniff GUI. It's a funny old business we're in!Seriously, both FreeBSD and Linux use the
HLT (halt) instruction when the system is
idle thus lowering its energy consumption and therefore the
heat it generates. Also if you have APM (advanced power
management) configured, then FreeBSD can also put the CPU into
a low power mode.Who is scratching in my memory banks??Q. Is there anything odd that FreeBSD
does when compiling the kernel which would cause the memory to
make a scratchy sound? When compiling (and for a brief moment
after recognizing the floppy drive upon startup, as well), a
strange scratchy sound emanates from what appears to be the
memory banks.A. Yes! You will see frequent references to
daemons in the BSD documentation, and what most
people do not know is that this refers to genuine, non-corporeal
entities that now possess your computer. The scratchy sound
coming from your memory is actually high-pitched whispering
exchanged among the daemons as they best decide how to deal
with various system administration tasks.If the noise gets to you, a good
fdisk /mbr from DOS will get rid of them,
but do not be surprised if they react adversely and try to stop
you. In fact, if at any point during the exercise you hear the
satanic voice of Bill Gates coming from the built-in speaker,
take off running and don't ever look back! Freed from the
counterbalancing influence of the BSD daemons, the twin demons
of DOS and Windows are often able to re-assert total control
over your machine to the eternal damnation of your soul.
Now that you know, given a choice you would probably prefer to get
used to the scratchy noises, no?What does MFC mean?MFC is an acronym for Merged From -CURRENT.
It is used in the CVS logs to denote when a change was
migrated from the CURRENT to the STABLE branches.What does BSD mean?It stands for something in a secret language that only
members can know. It does not translate literally but its ok
to tell you that BSD's translation is something between,
Formula-1 Racing Team, Penguins are
tasty snacks, and We have a better sense of
humor than Linux. :-)Seriously, BSD is an acronym for Berkeley
Software Distribution, which is the name the
Berkeley CSRG (Computer Systems Research
Group) chose for their Unix distribution way back when.What is a repo-copy?A repo-copy (which is a short form of repository
copy) refers to the direct copying of files within
the CVS repository.Without a repo-copy, if a file needed to be copied or
moved to another place in the repository, the committer would
run cvs add to put the file in its new
location, and then cvs rm on the old file
if the old copy was being removed.The disadvantage of this method is that the history
(i.e. the entries in the CVS logs) of the file would not be
copied to the new location. As the FreeBSD Project considers
this history very useful, a repository copy is often used
instead. This is a process where one of the repository meisters
will copy the files directly within the repository, rather than
using the &man.cvs.1; program.Why should I care what color the bikeshed is?The really, really short answer is that you should not.
The somewhat longer answer is that just because you are
capable of building a bikeshed doesn't mean you should stop
others from building one just because you don't like the
color they plan to paint it. This is a metaphor indicating
that you need not argue about every little feature just
because you know enough to do so. Some people have
commented that the amount of noise generated by a change is
inversely proportional to the complexity of the
change.The longer and more complete answer is that after a very
long argument about whether &man.sleep.1; should take
fractional second arguments, &a.phk; posted a long
message entitled A bike
shed (any colour will do) on greener grass....
The appropriate portions of that message are quoted
below.
&a.phk; on freebsd-hackers, October
2, 1999What is it about this bike shed? Some
of you have asked me.It is a long story, or rather it is an old story, but
it is quite short actually. C. Northcote Parkinson wrote
a book in the early 1960'ies, called Parkinson's
Law, which contains a lot of insight into the
dynamics of management.[snip a bit of commentary on the book]In the specific example involving the bike shed, the
other vital component is an atomic power-plant, I guess
that illustrates the age of the book.Parkinson shows how you can go in to the board of
directors and get approval for building a multi-million or
even billion dollar atomic power plant, but if you want to
build a bike shed you will be tangled up in endless
discussions.Parkinson explains that this is because an atomic
plant is so vast, so expensive and so complicated that
people cannot grasp it, and rather than try, they fall
back on the assumption that somebody else checked all the
details before it got this far. Richard P. Feynmann
gives a couple of interesting, and very much to the point,
examples relating to Los Alamos in his books.A bike shed on the other hand. Anyone can build one
of those over a weekend, and still have time to watch the
game on TV. So no matter how well prepared, no matter how
reasonable you are with your proposal, somebody will seize
the chance to show that he is doing his job, that he is
paying attention, that he is
here.In Denmark we call it setting your
fingerprint. It is about personal pride and
prestige, it is about being able to point somewhere and
say There! I did that.
It is a strong trait in politicians, but present in most
people given the chance. Just think about footsteps in
wet cement.
How many FreeBSD hackers does it take to change a
lightbulb?One thousand, one hundred and seventy-two:Twenty-three to complain to -CURRENT about the lights
being out;Four to claim that it is a configuration problem, and
that such matters really belong on -questions;Three to submit PRs about it, one of which is misfiled
under doc and consists only of "it's dark";One to commit an untested lightbulb which breaks
buildworld, then back it out five minutes later;Eight to flame the PR originators for not including
patches in their PRs;Five to complain about buildworld being broken;Thirty-one to answer that it works for them, and they
must have cvsupped at a bad time;One to post a patch for a new lightbulb to -hackers;One to complain that he had patches for this three years
ago, but when he sent them to -CURRENT they were just ignored,
and he has had bad experiences with the PR system; besides,
the proposed new lightbulb is non-reflexive;Thirty-seven to scream that lightbulbs do not belong in
the base system, that committers have no right to do things
like this without consulting the Community, and WHAT IS
-CORE DOING ABOUT IT!?Two hundred to complain about the color of the bicycle
shed;Three to point out that the patch breaks &man.style.9;;Seventeen to complain that the proposed new lightbulb is
under GPL;Five hundred and eighty-six to engage in a flame war
about the comparative advantages of the GPL, the BSD
license, the MIT license, the NPL, and the personal hygiene
of unnamed FSF founders;Seven to move various portions of the thread to -chat
and -advocacy;One to commit the suggested lightbulb, even though it
shines dimmer than the old one;Two to back it out with a furious flame of a commit
message, arguing that FreeBSD is better off in the dark than
with a dim lightbulb;Forty-six to argue vociferously about the backing out
of the dim lightbulb and demanding a statement from
-core;Eleven to request a smaller lightbulb so it will fit
their Tamagotchi if we ever decide to port FreeBSD to that
platform;Seventy-three to complain about the SNR on -hackers and
-chat and unsubscribe in protest;Thirteen to post "unsubscribe", "How do I unsubscribe?",
or "Please remove me from the list", followed by the usual
footer;One to commit a working lightbulb while everybody is too
busy flaming everybody else to notice;Thirty-one to point out that the new lightbulb would shine
0.364% brighter if compiled with TenDRA (although it will have
to be reshaped into a cube), and that FreeBSD should therefore
switch to TenDRA instead of EGCS;One to complain that the new lightbulb lacks
fairings;Nine (including the PR originators) to ask
"what is MFC?";Fifty-seven to complain about the lights being out two
weeks after the bulb has been changed.&a.nik; adds:I was laughing quite hard at
this.And then I thought,
"Hang on, shouldn't there be '1 to document it.' in that list somewhere?"And then I was enlightened :-)This entry is Copyright (c) 1999 &a.des;.
Please do not reproduce without attribution.Advanced TopicsWhat are SNAPs and RELEASEs?There are currently three active/semi-active branches
in the FreeBSD
CVS Repository (the RELENG_2 branch is probably
only changed twice a year, which is why there are only three
active branches of development):RELENG_2_2 AKA
2.2-STABLERELENG_3 AKA
3.X-STABLERELENG_4 AKA
4-STABLEHEAD AKA
-CURRENT AKA
5.0-CURRENTHEAD is not an actual branch tag,
like the other two; it is simply a symbolic constant for
the current, non-branched development
stream which we simply refer to as
-CURRENT.Right now, -CURRENT is the 5.0 development
stream and the 4-STABLE branch,
RELENG_4, forked off from
-CURRENT in Mar 2000.The 2.2-STABLE branch,
RELENG_2_2, departed -CURRENT in November
1996, and has pretty much been retired.How do I make my own custom release?To make a release you need to do three things: First,
you need to be running a kernel with the
&man.vn.4;
driver configured in. Add this to your kernel config file
and build a new kernel:pseudo-device vn #Vnode driver (turns a file into a device)Second, you have to have the whole CVS repository at
hand. To get this you can use CVSUP but in
your supfile set the release name to cvs and remove any tag or
date fields:*default prefix=/home/ncvs
*default base=/a
*default host=cvsup.FreeBSD.org
*default release=cvs
*default delete compress use-rel-suffix
## Main Source Tree
src-all
src-eBones
src-secure
# Other stuff
ports-all
www
doc-allThen run cvsup -g supfile to suck all
the good bits onto your box...Finally, you need a chunk of empty space to build into.
Let's say it is in /some/big/filesystem,
and from the example above you have got the CVS repository in
/home/ncvs:&prompt.root; setenv CVSROOT /home/ncvs # or export CVSROOT=/home/ncvs
&prompt.root; cd /usr/src
&prompt.root; make buildworld
&prompt.root; cd /usr/src/release
&prompt.root; make release BUILDNAME=3.0-MY-SNAP CHROOTDIR=/some/big/filesystem/releasePlease note that you do not
need to build world if you already have a populated
/usr/obj.An entire release will be built in
/some/big/filesystem/release and you
will have a full FTP-type installation in
/some/big/filesystem/release/R/ftp when
you are done. If you want to build your SNAP along some other
branch than -CURRENT, you can also add
RELEASETAG=SOMETAG to the make release
command line above, e.g. RELEASETAG=RELENG_2_2
would build an up-to-the- minute 2.2-STABLE snapshot.How do I create customized installation disks?The entire process of creating installation disks and
source and binary archives is automated by various targets in
/usr/src/release/Makefile. The information
there should be enough to get you started. However, it should
be said that this involves doing a make
world and will therefore take up a lot of time and
disk space.Why does make world clobber my existing
installed binaries?Yes, this is the general idea; as its name might suggest,
make world rebuilds every system binary from
scratch, so you can be certain of having a clean and consistent
environment at the end (which is why it takes so long).If the environment variable DESTDIR
is defined while running make world or
make install, the newly-created binaries
will be deposited in a directory tree identical to the
installed one, rooted at ${DESTDIR}.
Some random combination of shared libraries modifications and
program rebuilds can cause this to fail in make
world however.How come when my system boots, it says (bus speed
defaulted)?The Adaptec 1542 SCSI host adapters allow the user to
configure their bus access speed in software. Previous versions
of the 1542 driver tried to determine the fastest usable speed
and set the adapter to that. We found that this breaks some
users' systems, so you now have to define the
TUNE_1542 kernel configuration option in order
to have this take place. Using it on those systems where it
works may make your disks run faster, but on those systems
where it does not, your data could be corrupted.Can I follow current with limited Internet access?Yes, you can do this without
downloading the whole source tree by using the CTM facility.How did you split the distribution into 240k files?Newer BSD based systems have a
option to split that allows them to split files on arbitrary
byte boundaries.Here is an example from
/usr/src/Makefile.bin-tarball:
(cd ${DISTDIR}; \
tar cf - . \
gzip --no-name -9 -c | \
split -b 240640 - \
${RELEASEDIR}/tarballs/bindist/bin_tgz.)I have written a kernel extension, who do I send it
to?Please take a look at The Handbook entry on how to
+ URL="../../articles/contributing/index.html">The contributing to FreeBSD article on how to
submit code.And thanks for the thought!How are Plug N Play ISA cards detected and
initialized?By: Frank Durda IV
uhclem@nemesis.lonestar.orgIn a nutshell, there a few I/O ports that all of the
PnP boards respond to when the host asks if anyone is out
there. So when the PnP probe routine starts, he asks if there
are any PnP boards present, and all the PnP boards respond with
their model # to a I/O read of the same port, so the probe
routine gets a wired-OR yes to that question. At
least one bit will be on in that reply. Then the probe code is
able to cause boards with board model IDs (assigned by
Microsoft/Intel) lower than X to go off-line. It
then looks to see if any boards are still responding to the
query. If the answer was 0, then there are
no boards with IDs above X. Now probe asks if there are any
boards below X. If so, probe knows there are
boards with a model numbers below X. Probe then asks for boards
greater than X-(limit/4) to go off-line. If repeats the query.
By repeating this semi-binary search of IDs-in-range enough
times, the probing code will eventually identify all PnP boards
present in a given machine with a number of iterations that is
much lower than what 2^64 would take.The IDs are two 32-bit fields (hence 2ˆ64) + 8 bit
checksum. The first 32 bits are a vendor identifier. They never
come out and say it, but it appears to be assumed that
different types of boards from the same vendor could have
different 32-bit vendor ids. The idea of needing 32 bits just
for unique manufacturers is a bit excessive.The lower 32 bits are a serial #, Ethernet address,
something that makes this one board unique. The vendor must
never produce a second board that has the same lower 32 bits
unless the upper 32 bits are also different. So you can have
multiple boards of the same type in the machine and the full 64
bits will still be unique.The 32 bit groups can never be all zero. This allows the
wired-OR to show non-zero bits during the initial binary
search.Once the system has identified all the board IDs present,
it will reactivate each board, one at a time (via the same I/O
ports), and find out what resources the given board needs, what
interrupt choices are available, etc. A scan is made over all
the boards to collect this information.This info is then combined with info from any ECU files
on the hard disk or wired into the MLB BIOS. The ECU and BIOS
PnP support for hardware on the MLB is usually synthetic, and
the peripherals do not really do genuine PnP. However by
examining the BIOS info plus the ECU info, the probe routines
can cause the devices that are PnP to avoid those devices the
probe code cannot relocate.Then the PnP devices are visited once more and given
their I/O, DMA, IRQ and Memory-map address assignments. The
devices will then appear at those locations and remain there
until the next reboot, although there is nothing that says you
cannot move them around whenever you want.There is a lot of oversimplification above, but you
should get the general idea.Microsoft took over some of the primary printer status
ports to do PnP, on the logic that no boards decoded those
addresses for the opposing I/O cycles. I found a genuine IBM
printer board that did decode writes of the status port during
the early PnP proposal review period, but MS said
tough. So they do a write to the printer status
port for setting addresses, plus that use that address +
0x800, and a third I/O port for reading that
can be located anywhere between 0x200 and
0x3ff.Can you assign a major number for a device driver I have
written?This depends on whether or not you plan on making the
driver publicly available. If you do, then please send us a
copy of the driver source code, plus the appropriate
modifications to files.i386, a
sample configuration file entry, and the appropriate
&man.MAKEDEV.8;
code to create any special files your device uses. If you do
not, or are unable to because of licensing restrictions, then
character major number 32 and block major number 8 have been
reserved specifically for this purpose; please use them. In any
case, we would appreciate hearing about your driver on
&a.hackers;.What about alternative layout policies for
directories?In answer to the question of alternative layout policies
for directories, the scheme that is currently in use is
unchanged from what I wrote in 1983. I wrote that policy for
the original fast filesystem, and never revisited it. It works
well at keeping cylinder groups from filling up. As several of
you have noted, it works poorly for find. Most filesystems are
created from archives that were created by a depth first search
(aka ftw). These directories end up being striped across the
cylinder groups thus creating a worst possible scenario for
future depth first searches. If one knew the total number of
directories to be created, the solution would be to create
(total / fs_ncg) per cylinder group before moving on.
Obviously, one would have to create some heuristic to guess at
this number. Even using a small fixed number like say 10 would
make an order of magnitude improvement. To differentiate
restores from normal operation (when the current algorithm is
probably more sensible), you could use the clustering of up to
10 if they were all done within a ten second window. Anyway, my
conclusion is that this is an area ripe for
experimentation.Kirk McKusick, September 1998How can I make the most of the data I see when my kernel
panics?[This section was extracted from a mail
written by &a.wpaul; on the freebsd-current
mailing list by &a.des;, who
fixed a few typos and added the bracketed comments]
From: Bill Paul <wpaul@skynet.ctr.columbia.edu>
Subject: Re: the fs fun never stops
To: ben@rosengart.com
Date: Sun, 20 Sep 1998 15:22:50 -0400 (EDT)
Cc: current@FreeBSD.org[<ben@rosengart.com> posted the following
panic message]> Fatal trap 12: page fault while in kernel mode
> fault virtual address = 0x40
> fault code = supervisor read, page not present
> instruction pointer = 0x8:0xf014a7e5
^^^^^^^^^^
> stack pointer = 0x10:0xf4ed6f24
> frame pointer = 0x10:0xf4ed6f28
> code segment = base 0x0, limit 0xfffff, type 0x1b
> = DPL 0, pres 1, def32 1, gran 1
> processor eflags = interrupt enabled, resume, IOPL = 0
> current process = 80 (mount)
> interrupt mask =
> trap number = 12
> panic: page fault[When] you see a message like this, it is not enough to just
reproduce it and send it in. The instruction pointer value that
I highlighted up there is important; unfortunately, it is also
configuration dependent. In other words, the value varies
depending on the exact kernel image that you are using. If
you are using a GENERIC kernel image from one of the snapshots,
then it is possible for somebody else to track down the
offending function, but if you are running a custom kernel then
only you can tell us where the fault
occurred.What you should do is this:Write down the instruction pointer value. Note that
the 0x8: part at the beginning is not
significant in this case: it is the
0xf0xxxxxx part that we want.When the system reboots, do the following:
&prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxxx
where f0xxxxxx is the instruction
pointer value. The odds are you will not get an exact
match since the symbols in the kernel symbol table are
for the entry points of functions and the instruction
pointer address will be somewhere inside a function, not
at the start. If you do not get an exact match, omit the
last digit from the instruction pointer value and try
again, i.e.:
&prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxx
If that does not yield any results, chop off another
digit. Repeat until you get some sort of output. The
result will be a possible list of functions which caused
the panic. This is a less than exact mechanism for
tracking down the point of failure, but it is better than
nothing.I see people constantly show panic messages like this
but rarely do I see someone take the time to match up the
instruction pointer with a function in the kernel symbol
table.The best way to track down the cause of a panic is by
capturing a crash dump, then using
&man.gdb.1; to generate a stack trace on the
crash dump.In any case, the method I normally use is this:Set up a kernel config file, optionally adding
options DDB if you think you need
the kernel debugger for something. (I use this mainly
for setting breakpoints if I suspect an infinite loop
condition of some kind.)Use config -g
KERNELCONFIG to set
up the build directory.cd /sys/compile/
KERNELCONFIG; make
Wait for kernel to finish compiling.make installrebootThe &man.make.1; process will have built two kernels.
kernel and
kernel.debug. kernel
was installed as /kernel, while
kernel.debug can be used as the source of
debugging symbols for &man.gdb.1;.To make sure you capture a crash dump, you need edit
/etc/rc.conf and set
dumpdev to point to your swap
partition. This will cause the &man.rc.8; scripts
to use the &man.dumpon.8; command to enable crash
dumps. You can also run &man.dumpon.8; manually.
After a panic, the crash dump can be recovered using
&man.savecore.8;; if
dumpdev is set in
/etc/rc.conf, the &man.rc.8;
scripts will run &man.savecore.8; automatically
and put the crash dump in
/var/crash.FreeBSD crash dumps are usually the same size as the
physical RAM size of your machine. That is, if you have
64MB of RAM, you will get a 64MB crash dump. Therefore you
must make sure there is enough space in
/var/crash to hold the dump.
Alternatively, you run &man.savecore.8;
manually and have it recover the crash dump to another
directory where you have more room. It is possible to limit
the size of the crash dump by using options
MAXMEM=(foo) to set the amount of memory the
kernel will use to something a little more sensible. For
example, if you have 128MB of RAM, you can limit the
kernel's memory usage to 16MB so that your crash dump size
will be 16MB instead of 128MB.Once you have recovered the crash dump, you can get a
stack trace with &man.gdb.1; as follows:&prompt.user; gdb -k /sys/compile/KERNELCONFIG/kernel.debug /var/crash/vmcore.0(gdb)whereNote that there may be several screens worth of
information; ideally you should use
&man.script.1; to capture all of them. Using the
unstripped kernel image with all the debug symbols should show
the exact line of kernel source code where the panic occurred.
Usually you have to read the stack trace from the bottom up in
order to trace the exact sequence of events that lead to the
crash. You can also use &man.gdb.1; to print out
the contents of various variables or structures in order to
examine the system state at the time of the crash.Now, if you are really insane and have a second computer,
you can also configure &man.gdb.1; to do remote
debugging such that you can use &man.gdb.1; on
one system to debug the kernel on another system, including
setting breakpoints, single-stepping through the kernel code,
just like you can do with a normal user-mode program. I have not
played with this yet as I do not often have the chance to set up
two machines side by side for debugging purposes.[Bill adds: "I forgot to mention one thing: if
you have DDB enabled and the kernel drops into the debugger,
you can force a panic (and a crash dump) just by typing 'panic'
at the ddb prompt. It may stop in the debugger again during the
panic phase. If it does, type 'continue' and it will finish the
crash dump." -ed]Why has dlsym() stopped working for ELF executables?The ELF toolchain does not, by default, make the symbols
defined in an executable visible to the dynamic linker.
Consequently dlsym() searches on handles
obtained from calls to dlopen(NULL,
flags) will fail to find such symbols.If you want to search, using dlsym(),
for symbols present in the main executable of a process, you
need to link the executable using the
option to the
ELF
linker (&man.ld.1;).How can I increase or reduce the kernel address space?By default, the kernel address space is 256 MB on
FreeBSD 3.x and 1 GB on FreeBSD 4.x. If you run a
network-intensive server (e.g. a large FTP or HTTP server),
you might find that 256 MB is not enough.So how do you increase the address space? There are two
aspects to this. First, you need to tell the kernel to reserve
a larger portion of the address space for itself. Second, since
the kernel is loaded at the top of the address space, you need
to lower the load address so it does not bump its head against
the ceiling.The first goal is achieved by increasing the value of
NKPDE in
src/sys/i386/include/pmap.h. Here is what
it looks like for a 1 GB address space:#ifndef NKPDE
#ifdef SMP
#define NKPDE 254 /* addressable number of page tables/pde's */
#else
#define NKPDE 255 /* addressable number of page tables/pde's */
#endif /* SMP */
#endifTo find the correct value of NKPDE,
divide the desired address space size (in megabytes) by four,
then subtract one for UP and two for SMP.To achieve the second goal, you need to compute the
correct load address: simply subtract the address space size
(in bytes) from 0x100100000; the result is 0xc0100000 for a 1
GB address space. Set LOAD_ADDRESS in
src/sys/i386/conf/Makefile.i386 to that
value; then set the location counter in the beginning of the
section listing in
src/sys/i386/conf/kernel.script to the
same value, as follows:OUTPUT_FORMAT("elf32-i386", "elf32-i386", "elf32-i386")
OUTPUT_ARCH(i386)
ENTRY(btext)
SEARCH_DIR(/usr/lib); SEARCH_DIR(/usr/obj/elf/home/src/tmp/usr/i386-unknown-freebsdelf/lib);
SECTIONS
{
/* Read-only sections, merged into text segment: */
. = 0xc0100000 + SIZEOF_HEADERS;
.interp : { *(.interp) }Then reconfig and rebuild your kernel. You will probably
have problems with &man.ps.1;
&man.top.1; and the like; make
world should take care of it (or a manual rebuild of
libkvm,
&man.ps.1; and &man.top.1;
after copying the patched pmap.h to
/usr/include/vm/.NOTE: the size of the kernel address space must be a
multiple of four megabytes.[&a.dg; adds: I think the kernel address space
needs to be a power of two, but I am not certain about that. The
old(er) boot code used to monkey with the high order address bits
and I think expected at least 256MB
granularity.]Acknowledgments
FreeBSD Core TeamIf you see a problem with this FAQ, or wish to submit an
entry, please mail the &a.faq;. We appreciate your feedback,
and cannot make this a better FAQ without your help!
&a.jkh;Occasional fits of FAQ-reshuffling and updating.&a.dwhite;Services above and beyond the call of duty on
freebsd-questions&a.joerg;Services above and beyond the call of duty on
Usenet&a.wollman;Networking and formattingJim LoweMulticast information&a.pds;FreeBSD FAQ typing machine slaveyThe FreeBSD TeamKvetching, moaning, submitting dataAnd to any others we have forgotten, apologies and heartfelt
thanks!Bibliography4.4BSD System Manager's ManualComputer Systems Research Group, University of
California, BerkeleyO'Reilly and Associates1st EditionJune 1994804 pagesISBN 1-56592-080-54.4BSD User's Reference ManualComputer Systems Research Group, University of
California, BerkeleyO'Reilly and Associates1st EditionJune 1994905 pagesISBN 1-56592-075-94.4BSD User's Supplementary DocumentsComputer Systems Research Group, University of
California, BerkeleyO'Reilly and Associates1st EditionJune 1994712 pagesISBN 1-56592-076-74.4BSD Programmer's Reference ManualComputer Systems Research Group, University of
California, BerkeleyO'Reilly and Associates1st EditionJune 1994866 pagesISBN 1-56592-078-34.4BSD Programmer's Supplementary DocumentsComputer Systems Research Group, University of
California, BerkeleyO'Reilly and Associates1st EditionJune 1994596 pagesISBN 1-56592-079-1The Design and Implementation of the 4.4BSD Operating SystemM. K.McKusickKirkMarshallKeithBosticMichael JKarelsJohnQuartermanAddison-WesleyReadingMA1996ISBN 0-201-54979-4Unix System Administration HandbookEviNemethGarthSnyderScottSeebassTrent R.HeinJohnQuartermanPrentice-Hall3rd edition2000ISBN 0-13-020601-6The Complete FreeBSDGregLeheyWalnut Creek3rd editionJune 1999773 pagesISBN 1-57176-246-9The FreeBSD HandbookFreeBSD Documentation ProjectBSDi1st EditionNovember 1999489 pagesISBN 1-57176-241-8McKusick et al, 1994Berkeley Software Architecture Manual, 4.4BSD
EditionM. K.McKusickM. J.KarelsS. J.LefflerW. N.JoyR. S.Faber5:1-42
diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
index 763ca39c2a..a58777cc30 100644
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
@@ -1,300 +1,300 @@
OverviewWelcome to the FreeBSD Documentation Project. Good quality
documentation is very important to the success of FreeBSD, and the
FreeBSD Documentation Project (FDP) is how a lot of that documentation
is produced. Your contributions are very valuable.This document's main purpose is to clearly explain how
the FDP is organised, how to write and submit
documentation to the FDP, and how to
effectively use the tools available to you when writing
documentation.Membership
Every one is welcome to join the FDP. There is no minimum
membership requirement, no quota of documentation you need to
produce per month. All you need to do is subscribe to the
freebsd-doc@FreeBSD.org mailing list.After you have finished reading this document you should:Know which documentation is maintained by the FDP.Be able to read and understand the SGML source code for the
documentation maintained by the FDP.Be able to make changes to the documentation.Be able to submit your changes back for review and eventual
inclusion in the FreeBSD documentation.The FreeBSD Documentation SetThe FDP is responsible for four categories of FreeBSD
documentation.Manual pagesThe English language system manual pages are not written by
the FDP, as they are part of the base system. However, the FDP can
(and has) re-worded parts of existing manual pages to make them
clearer, or to correct inaccuracies.The translation teams are responsible for translating the
system manual pages in to different languages. These translations
are kept within the FDP.FAQThe FAQ aims to address (in short question and answer format)
questions that are asked, or should be asked, on the various
mailing lists and newsgroups devoted to FreeBSD. The format does
not permit long and comprehensive answers.HandbookThe Handbook aims to be the comprehensive on-line resource and
reference for FreeBSD users.Web siteThis is the main FreeBSD presence on the World Wide Web,
visible at http://www.FreeBSD.org/
+ url="../../../../index.html">http://www.FreeBSD.org/
and many mirrors around the world. The web site is many people's
first exposure to FreeBSD.These four groups of documentation are all available in the
FreeBSD CVS tree. This means that the logs of changes to these
files are visible to anyone, and anyone can use a program such as
CVSup or
CTM to keep local copies of
this documentation.In addition, many people have written tutorials or other web
sites relating to FreeBSD. Some of these are stored in the CVS
repository as well (where the author has agreed to this). In
other cases the author has decided to keep his documentation
separate from the main FreeBSD repository. The FDP endeavours to
provide links to as much of this documentation as
possible.Before you startThis document assumes that you already know:How to maintain an up-to-date local copy of the FreeBSD
documentation by maintaining a local copy of the
FreeBSD CVS repository (using CVS
and either CVSup or
CTM) or by using
CVSup to download just a
checked-out copy.How to download and install new software using either the
FreeBSD Ports system or &man.pkg.add.1;.Quick StartIf you just want to get going, and feel confident you can pick
things up as you go along, follow these instructions.Install the textproc/docproj
meta-port.&prompt.root; cd /usr/ports/textproc/docproj
&prompt.root; make JADETEX=no installGet a local copy of the FreeBSD doc tree.
Either use CVSup in checkout mode to do this, or
get a full copy of the CVS repository locally.If you have the CVS repository locally then as a minimum you
will need to checkout the doc/share, and
doc/en_US.ISO8859-1/share
directories.&prompt.user; cvs checkout doc/share
&prompt.user; cvs checkout doc/en_US.ISO8859-1/shareIf you have plenty of disk space then you could check out
everything.&prompt.user; cvs checkout docIf you are preparing a change to an existing book or article,
check it out of the repository as necessary. If you are planning on
contributing a new book or article then use an existing one as a
guide.For example, if you want to contribute a new article about
setting up a VPN between FreeBSD and Windows 2000 you might do the
following.Check out the articles
directory.&prompt.user; cvs checkout doc/en_US.ISO8859-1/articlesCopy an existing article to use as a template. In this
case, you have decided that your new article belongs in a
directory called vpn-w2k.&prompt.user; cd doc/en_US.ISO8859-1/articles
&prompt.user; cp -r committers-guide vpn-w2kIf you wanted to edit an existing document, such as the the FAQ,
which is in doc/en_US.ISO8859-1/books/faq you
would check it out of the repository like this.&prompt.user; cvs checkout doc/en_US.ISO8859-1/books/faqEdit the .sgml files using your editor of
choice.Test the markup using the lint
target. This will quickly find any errors in the document
without actually performing the time-consuming
transformation.&prompt.user; make lintWhen you are ready to actually build the document, you
may specify a single format or a list of formats in the
FORMATS variable. Currently,
html, html-split,
txt, ps,
pdf, and rtf are
supported. The most up to date list of supported formats is
listed at the top of the
doc/share/mk/doc.docbook.mk file. Make
sure to use quotes around the list of formats when you build
more than one format with a single command.For example, to convert the document to
html only, you would use:&prompt.user; make FORMATS=htmlBut when you want to convert the document to both
html and txt format,
you could use either two separate &man.make.1; runs,
with:&prompt.user; make FORMATS=html
&prompt.user; make FORMATS=txtor, you can do it in one command:&prompt.user; make FORMATS="html txt"Submit your changes using &man.send-pr.1;.
diff --git a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
index 981812ec6e..0d7f5b2aa0 100644
--- a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
@@ -1,134 +1,134 @@
See AlsoThis document is deliberately not an exhaustive discussion of SGML,
the DTDs listed, and the FreeBSD Documentation Project. For more
information about these, you are encouraged to see the following web
sites.The FreeBSD Documentation Project
- The FreeBSD
+ The FreeBSD
Documentation Project web pages
- The FreeBSD Handbook
+ The FreeBSD HandbookSGMLThe SGML/XML web
page, a comprehensive SGML resourceGentle introduction to SGMLHTMLThe World Wide Web
ConsortiumThe HTML 4.0
specificationDocBookThe DocBook
Technical Committee, maintainers of the DocBook DTDDocBook: The Definitive
Guide, the online documentation for the DocBook
DTD.
- The DocBook Open
+ The DocBook Open
Repository contains DSSSL stylesheets and other resources
for people using DocBook.The Linux Documentation ProjectThe Linux Documentation
Project web pages
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 39313fb747..7d90a804ad 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -1,2600 +1,2600 @@
SGML MarkupThis chapter describes the two markup languages you will encounter
when you contribute to the FreeBSD documentation project. Each section
describes the markup language, and details the markup that you are likely
to want to use, or that is already in use.These markup languages contain a large number of elements, and it can
be confusing sometimes to know which element to use for a particular
situation. This section goes through the elements you are most likely to
need, and gives examples of how you would use them.This is not an exhaustive list of elements, since
that would just reiterate the documentation for each language. The aim of
this section is to list those elements more likely to be useful to you.
If you have a question about how best to markup a particular piece of
content, please post it to the FreeBSD Documentation Project mailing list
freebsd-doc@FreeBSD.org.Inline vs. blockIn the remainder of this document, when describing elements,
inline means that the element can occur within a
block element, and does not cause a line break. A
block element, by comparison, will cause a line
break (and other processing) when it is encountered.HTMLHTML, the HyperText Markup Language, is the markup language of
choice on the World Wide Web. More information can be found at
<URL:http://www.w3.org/>.HTML is used to markup pages on the FreeBSD web site. It should not
(generally) be used to mark up other documention, since DocBook offers a
far richer set of elements to choose from. Consequently, you will
normally only encounter HTML pages if you are writing for the web
site.HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
latest, 4.0 (available in both strict and
loose variants).The HTML DTDs are available from the ports collection in the
textproc/html port. They are automatically
installed as part of the textproc/docproj
port.Formal Public Identifier (FPI)There are a number of HTML FPIs, depending upon the version (also
known as the level) of HTML that you want to declare your document to
be compliant with.The majority of HTML documents on the FreeBSD web site comply with
the loose version of HTML 4.0.PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"Sectional elementsAn HTML document is normally split in to two sections. The first
section, called the head, contains
meta-information about the document, such as its title, the name of
the author, the parent document, and so on. The second section, the
body, contains the content that will be displayed
to the user.These sections are indicated with head and
body elements respectively. These elements are
contained within the top-level html element.Normal HTML document structure<html>
<head>
<title>The document's title</title>
</head>
<body>
…
</body>
</html>Block elementsHeadingsHTML allows you to denote headings in your document, at up to
six different levels.The largest and most prominent heading is h1,
then h2, continuing down to
h6.The element's content is the text of the heading.h1, h2, etc.Use:First section
This is the heading for the first section
This is the heading for the first sub-section
This is the heading for the second section
]]>Generally, an HTML page should have one first level heading
(h1). This can contain many second level
headings (h2), which can in turn contain many
third level headings. Each
hn element should have
the same element, but one further up the hierarchy, preceeding it.
Leaving gaps in the numbering is to be avoided.Bad ordering of
hn elementsUse:First section
Sub-section
]]>ParagraphsHTML supports a single paragraph element,
p.pUse:This is a paragraph. It can contain just about any
other element.
]]>
Block quotationsA block quotation is an extended quotation from another document
that should not appear within the current paragraph.blockquoteUse:A small excerpt from the US Constitution:
We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic
Tranquility, provide for the common defence, promote the general
Welfare, and secure the Blessings of Liberty to ourselves and our
Posterity, do ordain and establish this Constitution for the
United States of America.
]]>ListsYou can present the user with three types of lists, ordered,
unordered, and definition.Typically, each entry in an ordered list will be numbered, while
each entry in an unordered list will be preceded by a bullet point.
Definition lists are composed of two sections for each entry. The
first section is the term being defined, and the second section is
the definition of the term.Ordered lists are indicated by the ol
element, unordered lists by the ul element, and
definition lists by the dl element.Ordered and unordered lists contain listitems, indicated by the
li element. A listitem can contain textual
content, or it may be further wrapped in one or more
p elements.Definition lists contain definition terms
(dt) and definition descriptions
(dd). A definition term can only contain inline
elements. A definition description can contain other block
elements.ul and olUse:An unordered list. Listitems will probably be
preceeded by bullets.
First item
Second item
Third item
An ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be
numbered.
This is the first item. It only has one paragraph.
This is the first paragraph of the second item.
This is the second paragraph of the second item.
This is the first and only paragraph of the third
item.
]]>Definition lists with dlUse:
Term 1
Paragraph 1 of definition 1.
Paragraph 2 of definition 1.
Term 2
Paragraph 1 of definition 2.
Term 3
Paragraph 1 of definition 3. Note that the <p>
element is not required in the single paragraph case.
]]>Pre-formatted textYou can indicate that text should be shown to the user exactly
as it is in the file. Typically, this means that the text is shown
in a fixed font, multiple spaces are not merged in to one, and line
breaks in the text are significant.In order to do this, wrap the content in the
pre element.preYou could use pre to mark up an e-mail
message; From: nik@FreeBSD.org
To: freebsd-doc@FreeBSD.org
Subject: New documentation available
There's a new copy of my primer for contributers to the FreeBSD
Documentation Project available at
Comments appreciated.
N]]>TablesMost text-mode browsers (such as Lynx) do not render tables
particularly effectively. If you are relying on the tabular
display of your content, you should consider using alternative
markup to prevent confusion.Mark up tabular information using the table
element. A table consists of one or more table rows
(tr), each containing one or more cells of table
data (td). Each cell can contain other block
elements, such as paragraphs or lists. It can also contain another
table (this nesting can repeat indefinitely). If the cell only
contains one paragraph then you do not need to include the
p element.Simple use of tableUse:This is a simple 2x2 table.
Top left cell
Top right cell
Bottom left cell
Bottom right cell
]]>A cell can span multiple rows and columns. To indicate this,
add the rowspan and/or colspan
attributes, with values indicating the number of rows of columns
that should be spanned.Using rowspanUse:One tall thin cell on the left, two short cells next to
it on the right.
Long and thin
Top cell
Bottom cell
]]>Using colspanUse:One long cell on top, two short cells below it.
Top cell
Bottom left cell
Bottom right cell
]]>Using rowspan and
colspan togetherUse:On a 3x3 grid, the top left block is a 2x2 set of
cells merged in to one. The other cells are normal.
Top left large cell
Top right cell
Middle right cell
Bottom left cell
Bottom middle cell
Bottom right cell
]]>In-line elementsEmphasising informationYou have two levels of emphasis available in HTML,
em and strong.
em is for a normal level of emphasis and
strong indicates stronger emphasis.Typically, em is rendered in italic and
strong is rendered in bold. This is not always
the case, however, and you should not rely on it.em and strongUse:This has been emphasised, while
this has been strongly emphasised.]]>Bold and italicsBecause HTML includes presentational markup, you can also
indicate that particular content should be rendered in bold or
italic. The elements are b and
i respectively.b and iThis is in bold, while this is
in italics.]]>Indicating fixed pitch textIf you have content that should be rendered in a fixed pitch
(typewriter) typeface, use tt (for
teletype).ttUse:This document was originally written by
Nik Clayton, who can be reached by e-mail as
nik@FreeBSD.org.]]>Content sizeYou can indicate that content should be shown in a larger or
smaller font. There are three ways of doing this.Use big and small
around the content you wish to change size. These tags can be
nested, so <big><big>This is much
bigger</big></big> is possible.Use font with the size
attribute set to +1 or -1
respectively. This has the same effect as using
big or small. However,
the use of this approach is deprecated.Use font with the size
attribute set to a number between 1 and 7. The default font size
is 3. This approach is deprecated.big, small, and
fontThe following fragments all do the same thing.This text is slightly smaller. But
this text is slightly bigger.
This text is slightly smaller. But
this text is slightly bigger
This text is slightly smaller. But
this text is slightly bigger.
]]>
LinksLinks are also in-line elements.Linking to other documents on the WWWIn order to include a link to another document on the WWW you
must know the URL of the document you want to link to.The link is indicated with a, and the
href attribute contains the URL of the target
document. The content of the element becomes the link, and is
normally indicated to the user in some way (underlining, change of
colour, different mouse cursor when over the link, and so
on).Using <a href="...">Use:More information is available at the
FreeBSD web site.]]>These links will take the user to the top of the chosen
document.Linking to other parts of documentsLinking to a point within another document (or within the same
document) requires that the document author include anchors that you
can link to.Anchors are indicated with a and the
name attribute instead of
href.Using <a name="...">Use:This paragraph can be referenced
in other links with the name para1.]]>To link to a named part of a document, write a normal link to
that document, but include the name of the anchor after a
# symbol.Linking to a named part of another documentAssume that the para1 example resides in a
document called foo.html.More information can be found in the
first paragraph of
foo.html.]]>If you are linking to a named anchor within the same document
then you can omit the document's URL, and just include the name of
the anchor (with the preceeding #).Linking to a named part of the same documentAssume that the para1 example resides in
this documentMore information can be found in the
first paragraph of this
document.]]>DocBookDocBook was designed by the Davenport Group to be
a DTD for writing technical documentation. As such, and unlike LinuxDoc
and HTML, DocBook is very heavily oriented towards markup that
describes what something is, rather than describing
how it should be presented.formal vs. informalSome elements may exist in two forms, formal
and informal. Typically, the formal version of
the element will consist of a title followed by the information
version of the element. The informal version will not have a
title.The DocBook DTD is available from the ports collection in the
textproc/docbook port. It is automatically
installed as part of the textproc/docproj
port.FreeBSD extensionsThe FreeBSD Documentation Project has extended the DocBook DTD by
adding some new elements. These elements serve to make some of the
markup more precise.Where a FreeBSD specific element is listed below it is clearly
marked.Throughout the rest of this document, the term
DocBook is used to mean the FreeBSD extended DocBook
DTD.There is nothing about these extensions that is FreeBSD
specific, it was just felt that they were useful enhancements for
this particular project. Should anyone from any of the other *nix
camps (NetBSD, OpenBSD, Linux, …) be interested in
collaborating on a standard DocBook extension set, please get in
touch with Nik Clayton nik@FreeBSD.org.The FreeBSD extensions are not (currently) in the ports
collection. They are stored in the FreeBSD CVS tree, as doc/share/sgml/freebsd.dtd.
+ url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd.
Formal Public Identifier (FPI)In compliance with the DocBook guidelines for writing FPIs for
DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
is;PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"Document structureDocBook allows you to structure your documentation in several
ways. In the FreeBSD Documentation Project we are using two primary
types of DocBook document: the book and the article.A book is organised into chapters. This is a
mandatory requirement. There may be parts between
the book and the chapter to provide another layer of organisation.
The Handbook is arranged in this way.A chapter may (or may not) contain one or more sections. These
are indicated with the sect1 element. If a section
contains another section then use the sect2
element, and so on, up to sect5.Chapters and sections contain the remainder of the content.An article is simpler than a book, and does not use chapters.
Instead, the content of an article is organised into one or more
sections, using the same sect1 (and
sect2 and so on) elements that are used in
books.Obviously, you should consider the nature of the documentation you
are writing in order to decide whether it is best marked up as a book
or an article. Articles are well suited to information that does not
need to be broken down into several chapters, and that is, relatively
speaking, quite short, at up to 20-25 pages of content. Books are
best suited to information that can be broken up into several
chapters, possibly with appendices and similar content as well.
- The FreeBSD
+ The FreeBSD
tutorials are all marked up as articles, while this
- document, the FreeBSD
+ document, the FreeBSD
FAQ, and the FreeBSD Handbook are
+ url="../handbook/index.html">FreeBSD Handbook are
all marked up as books.Starting a bookThe content of the book is contained within the
book element. As well as containing structural
markup, this element can contain elements that include additional
information about the book. This is either meta-information, used
for reference purposes, or additional content used to produce a
title page.This additional information should be contained within
bookinfo.Boilerplate book with
bookinfo<book>
<bookinfo>
<title>Your title here</title>
<author>
<firstname>Your first name</firstname>
<surname>Your surname</surname>
<affiliation>
<address><email>Your e-mail address</email></address>
</affiliation>
</author>
<copyright>
<year>1998</year>
<holder role="mailto:your e-mail address">Your name</holder>
</copyright>
<pubdate role="rcs">$Date$</pubdate>
<releaseinfo>$Id$</releaseinfo>
<abstract>
<para>Include an abstract of the book's contents here.</para>
</abstract>
</bookinfo>
…
</book>Starting an articleThe content of the article is contained within the
article element. As well as containing
structural markup, this element can contain elements that include
additional information about the article. This is either
meta-information, used for reference purposes, or additional content
used to produce a title page.This additional information should be contained within
articleinfo.Boilerplate article with
articleinfo<article>
<articleinfo>
<title>Your title here</title>
<author>
<firstname>Your first name</firstname>
<surname>Your surname</surname>
<affiliation>
<address><email>Your e-mail address</email></address>
</affiliation>
</author>
<copyright>
<year>1998</year>
<holder role="mailto:your e-mail address">Your name</holder>
</copyright>
<pubdate role="rcs">$Date$</pubdate>
<releaseinfo>$Id$</releaseinfo>
<abstract>
<para>Include an abstract of the article's contents here.</para>
</abstract>
</articleinfo>
…
</article>Indicating chaptersUse chapter to mark up your chapters. Each
chapter has a mandatory title. Articles do not
contain chapters, they are reserved for books.A simple chapterThe chapter's title
...
]]>A chapter cannot be empty; it must contain elements in addition
to title. If you need to include an empty
chapter then just use an empty paragraph.Empty chaptersThis is an empty chapter
]]>Sections below chaptersIn books, chapters may (but do not need to) be broken up into
sections, subsections, and so on. In articles, sections are the
main structural element, and each article must contain at least one
section. Use the
sectn element. The
n indicates the section number, which
identifies the section level.The first sectn is
sect1. You can have one or more of these in a
chapter. They can contain one or more sect2
elements, and so on, down to sect5.Sections in chaptersA sample chapterSome text in the chapter.First section (1.1)
…
Second section (1.2)First sub-section (1.2.1)First sub-sub-section (1.2.1.1)
…
Second sub-section (1.2.2)
…
]]>This example includes section numbers in the section titles.
You should not do this in your documents. Adding the section
numbers is carried out by the stylesheets (of which more
later), and you do not need to manage them yourself.Subdividing using partsYou can introduce another layer of organisation between
book and chapter with one or
more parts. This cannot be done in an
article.IntroductionOverview
...
What is FreeBSD?
...
History
...
]]>Block elementsParagraphsDocBook supports three types of paragraphs:
formalpara, para, and
simpara.Most of the time you will only need to use
para. formalpara includes a
title element, and simpara
disallows some elements from within para. Stick
with para.paraUse:This is a paragraph. It can contain just about any
other element. ]]>Appearance:This is a paragraph. It can contain just about any other
element.Block quotationsA block quotation is an extended quotation from another document
that should not appear within the current paragraph. You will
probably only need it infrequently.Blockquotes can optionally contain a title and an attribution
(or they can be left untitled and unattributed).blockquoteUse:A small excerpt from the US Constitution;
Preamble to the Constitution of the United StatesCopied from a web site somewhereWe the People of the United States, in Order to form a more perfect
Union, establish Justice, insure domestic Tranquility, provide for the
common defence, promote the general Welfare, and secure the Blessings
of Liberty to ourselves and our Posterity, do ordain and establish this
Constitution for the United States of America.
]]>Appearance:
Preamble to the Constitution of the United StatesCopied from a web site somewhereWe the People of the United States, in Order to form a more
perfect Union, establish Justice, insure domestic Tranquility,
provide for the common defence, promote the general Welfare, and
secure the Blessings of Liberty to ourselves and our Posterity,
do ordain and establish this Constitution for the United States
of America.
Tips, notes, warnings, cautions, important information and
sidebars.You may need to include extra information separate from the
main body of the text. Typically this is meta
information that the user should be aware of.Depending on the nature of the information, one of
tip, note,
warning, caution, and
important should be used. Alternatively, if the
information is related to the main text but is not one of the above,
use sidebar.The circumstances in which to choose one of these elements over
another is unclear. The DocBook documentation suggests;A Note is for information that should be heeded by all
readers.An Important element is a variation on Note.A Caution is for information regarding possible data loss
or software damage.A Warning is for information regarding possible hardware
damage or injury to life or limb.warningUse:Installing FreeBSD may make you want to delete Windows from your
harddisk.
]]>Installing FreeBSD may make you want to delete Windows from
your harddisk.Lists and proceduresYou will often need to list pieces of information to the user,
or present them with a number of steps that must be carried out in
order to accomplish a particular goal.In order to do this, use itemizedlist,
orderedlist, or
procedureThere are other types of
list element in DocBook, but we're not concerned with those at
the moment.itemizedlist and
orderedlist are similar to their counterparts in
HTML, ul and ol. Each one
consists of one or more listitem elements, and
each listitem contains one or more block
elements. The listitem elements are analagous to
HTML's li tags. However, unlike HTML, they are
required.procedure is slightly different. It consists
of steps, which may in turn consists of more
steps or substeps. Each
step contains block elements.itemizedlist,
orderedlist, and
procedureUse:This is the first itemized item.This is the second itemized item.This is the first ordered item.This is the second ordered item.Do this.Then do this.And now do this.]]>Appearance:This is the first itemized item.This is the second itemized item.This is the first ordered item.This is the second ordered item.Do this.Then do this.And now do this.Showing file samplesIf you want to show a fragment of a file (or perhaps a complete
file) to the user, wrap it in the programlisting
element.White space and line breaks within
programlistingare
significant. In particular, this means that the opening tag should
appear on the same line as the first line of the output, and the
closing tag should appear on the same line as the last line of the
output, otherwise spurious blank lines may be included.programlistingUse:When you have finished, your program should look like
this;
#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
}]]>Notice how the angle brackets in the
#include line need to be referenced by their
entities instead of being included literally.Appearance:When you have finished, your program should look like
this;#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
}CalloutsA callout is a mechanism for referring back to an earlier piece
of text or specific position within an earlier example without
linking to it within the text.To do this, mark areas of interest in your example
(programlisting,
literallayout, or whatever) with the
co element. Each element must have a unique
id assigned to it. After the example include a
calloutlist that refers back to the example and
provides additional commentary.co and
calloutlistWhen you have finished, your program should look like
this;
#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
}Includes the standard IO header file.Specifies that main() returns an
int.The printf() call that writes
hello, world to standard output.]]>Appearance:When you have finished, your program should look like
this;#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
}Includes the standard IO header file.Specifies that main() returns an
int.The printf() call that writes
hello, world to standard output.TablesUnlike HTML, you do not need to use tables for layout purposes,
as the stylesheet handles those issues for you. Instead, just use
tables for marking up tabular data.In general terms (and see the DocBook documentation for more
detail) a table (which can be either formal or informal) consists of
a table element. This contains at least one
tgroup element, which specifies (as an attribute)
the number of columns in this table group. Within the tablegroup
you can then have one thead element, which
contains elements for the table headings (column headings), and one
tbody which contains the body of the
table.Both tgroup and thead
contain row elements, which in turn contain
entry elements. Each entry
element specifies one cell in the table.informaltableUse:This is column head 1This is column head 2Row 1, column 1Row 1, column 2Row 2, column 1Row 2, column 2
]]>Appearance:This is column head 1This is column head 2Row 1, column 1Row 1, column 2Row 2, column 1Row 2, column 2If you don't want a border around the table the
frame attribute can be added to the
informaltable element with a value of
none (i.e., <informaltable
frame="none">).Tables where frame="none"Appearance:This is column head 1This is column head 2Row 1, column 1Row 1, column 2Row 2, column 1Row 2, column 2Examples for the user to followA lot of the time you need to show examples for the user to
follow. Typically, these will consist of dialogs with the computer;
the user types in a command, the user gets a response back, they
type in another command, and so on.A number of distinct elements and entities come in to play
here.screenEverything the user sees in this example will be on the
computer screen, so the next element is
screen.Within screen, white space is
significant.prompt,
&prompt.root; and
&prompt.user;Some of the things the user will be seeing on the screen
are prompts from the computer (either from the OS, command
shell, or application. These should be marked up using
prompt.As a special case, the two shell prompts for the normal
user and the root user have been provided as entities. Every
time you want to indicate the user is at a shell prompt, use
one of &prompt.root; and
&prompt.user; as necessary. They do
not need to be inside prompt.&prompt.root; and
&prompt.user; are FreeBSD
extensions to DocBook, and are not part of the original
DTD.userinputWhen displaying text that the user should type in, wrap it
in userinput tags. It will probably be
displayed differently to the user.screen, prompt, and
userinputUse:&prompt.user; ls -1
foo1
foo2
foo3
&prompt.user; ls -1 | grep foo2
foo2
&prompt.user; suPassword:
&prompt.root; cat foo2
This is the file called 'foo2']]>Appearance:&prompt.user; ls -1
foo1
foo2
foo3
&prompt.user; ls -1 | grep foo2
foo2
&prompt.user; suPassword:
&prompt.root; cat foo2
This is the file called 'foo2'Even though we are displaying the contents of the file
foo2, it is not marked
up as programlisting. Reserve
programlisting for showing fragments of files
outside the context of user actions.In-line elementsEmphasising informationWhen you want to emphasise a particular word or phrase, use
emphasis. This may be presented as italic, or
bold, or might be spoken differently with a text-to-speech
system.There is no way to change the presentation of the emphasis
within your document, no equivalent of HTML's b
and i. If the information you are presenting is
important then consider presenting it in
important rather than
emphasis.emphasisUse:FreeBSD is without doubt the
premiere Unix like operating system for the Intel architecture.]]>Appearance:FreeBSD is without doubt the premiere Unix
like operating system for the Intel architecture.Keys, mouse buttons, and combinationsTo refer to a specific key on the keyboard, use
keycap. To refer to a mouse button, use
mousebutton. And to refer to combinations of key
presses or mouse clicks, wrap them all in
keycombo.keycombo has an attribute called
action, which may be one of
click, double-click,
other, press,
seq, or simul. The last two
values denote whether the keys or buttons should be pressed in
sequence, or simultaneously.The stylesheets automatically add any connecting symbols, such
as +, between the key names, when wrapped in
keycombo.Keys, mouse buttons, and combinationsUse:To switch to the second virtual terminal, press
AltF1.
To exit vi without saving your work, type
Esc:q!.My window manager is configured so that
Altright mouse button is used to move windows.]]>Appearance:To switch to the second virtual terminal, press
AltF1.To exit vi without saving your work, type
Esc:q!.My window manager is configured so that
Altright mouse button is used to move windows.Applications, commands, options, and citesYou will frequently want to refer to both applications and
commands when writing for the Handbook. The distinction between
them is simple: an application is the name for a suite (or possibly
just 1) of programs that fulfil a particular task. A command is the
name of a program that the user can run.In addition, you will occasionally need to list one or more of
the options that a command might take.Finally, you will often want to list a command with its manual
section number, in the command(number) format so
common in Unix manuals.Mark up application names with
application.When you want to list a command with its manual section number
(which should be most of the time) the DocBook element is
citerefentry. This will contain a further two
elements, refentrytitle and
manvolnum. The content of
refentrytitle is the name of the command, and the
content of manvolnum is the manual page
section.This can be cumbersome to write, and so a series of general entities
have been created to make this easier. Each entity takes the form
&man.manual-page.manual-section;.The file that contains these entities is in
doc/share/sgml/man-refs.ent, and can be
referred to using this FPI:PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"Therefore, the introduction to your documentation will probably
look like this:<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
…
]>Use command when you want to include a
command name in-line but present it as something the
user should type in.Use option to mark up a command's
options.This can be confusing, and sometimes the choice is not always
clear. Hopefully this example makes it clearer.Applications, commands, and options.Use:Sendmail is the most
widely used Unix mail application.
Sendmail includes the
sendmail8, &man.mailq.8;, and &man.newaliases.8;
programs.One of the command line parameters to sendmail8, , will display the current
status of messages in the mail queue. Check this on the command
line by running sendmail -bp.]]>Appearance:Sendmail is the most widely used
Unix mail application.Sendmail includes the
sendmail8, mailq8, and newaliases8 programs.One of the command line parameters to sendmail8, , will display the current
status of messages in the mail queue. Check this on the command
line by running sendmail -bp.Notice how the
&man.command.section; notation is easier to follow.Files, directories, extensionsWhenever you wish to refer to the name of a file, a directory,
or a file extension, use filename.filenameUse:The SGML source for the Handbook in English can be
found in /usr/doc/en/handbook/. The first
file is called handbook.sgml in that
directory. You should also see a Makefile
and a number of files with a .ent
extension.]]>Appearance:The SGML source for the Handbook in English can be found in
/usr/doc/en/handbook/. The first file is
called handbook.sgml in that directory. You
should also see a Makefile and a number of
files with a .ent extension.DevicesFreeBSD extensionThese elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.When referring to devices you have two choices. You can either
refer to the device as it appears in /dev, or
you can use the name of the device as it appears in the kernel. For
this latter course, use devicename.Sometimes you will not have a choice. Some devices, such as
networking cards, do not have entries in /dev,
or the entries are markedly different from those entries.devicenameUse:sio is used for serial
communication in FreeBSD. sio manifests
through a number of entries in /dev, including
/dev/ttyd0 and /dev/cuaa0.
By contrast, the networking devices, such as
ed0 do not appear in /dev.
In MS-DOS, the first floppy drive is referred to as
a:. In FreeBSD it is
/dev/fd0.]]>Appearance:sio is used for serial communication
in FreeBSD. sio manifests through a
number of entries in /dev, including
/dev/ttyd0 and
/dev/cuaa0.By contrast, the networking devices, such as
ed0 do not appear in
/dev.In MS-DOS, the first floppy drive is referred to as
a:. In FreeBSD it is
/dev/fd0.Hosts, domains, IP addresses, and so forthFreeBSD extensionThese elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.You can markup identification information for networked
computers (hosts) in several ways, depending on the nature of the
information. All of them use hostid as the
element, with the role attribute selecting the
type of the marked up information.No role attribute, or
role="hostname"With no role attribute (i.e.,
hostid...hostid the
marked up information is the simple hostname, such as
freefall or wcarchive.
You can explicitly specify this with
role="hostname".role="domainname"The text is a domain name, such as
FreeBSD.org or
ngo.org.uk. There is no hostname
component.role="fqdn"The text is a Fully Qualified Domain Name, with both
hostname and domain name parts.role="ipaddr"The text is an IP address, probably expressed as a dotted
quad.role="ip6addr"The text is an IPv6 address.role="netmask"The text is a network mask, which might be expressed as a
dotted quad, a hexadecimal string, or as a
/ followed by a number.role="mac"The text is an Ethernet MAC address, expressed as a series
of 2 digit hexadecimal numbers separated by colons.hostid and rolesUse:The local machine can always be referred to by the
name localhost, which will have the IP address
127.0.0.1.
The FreeBSD.org domain
contains a number of different hosts, including
freefall.FreeBSD.org and
bento.FreeBSD.org.When adding an IP alias to an interface (using
ifconfig) always use a
netmask of 255.255.255.255
(which can also be expressed as 0xffffffff.The MAC address uniquely identifies every network card
in existence. A typical MAC address looks like 08:00:20:87:ef:d0.]]>Appearance:The local machine can always be referred to by the name
localhost, which will have the IP address 127.0.0.1.The FreeBSD.org domain
contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org.When adding an IP alias to an interface (using
ifconfig) always use a
netmask of 255.255.255.255 (which
can also be expressed as 0xffffffff.The MAC address uniquely identifies every network card in
existence. A typical MAC address looks like 08:00:20:87:ef:d0.UsernamesFreeBSD extensionThese elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.When you need to refer to a specific username, such as
root or bin, use
username.usernameUse:To carry out most system administration functions you
will need to be root.]]>Appearance:To carry out most system administration functions you will
need to be root.Describing MakefilesFreeBSD extensionThese elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.Two elements exist to describe parts of
Makefiles, maketarget and
makevar.maketarget identifies a build target exported
by a Makefile that can be given as a parameter
to make. makevar identifies a
variable that can be set (in the environment, on the
make command line, or within the
Makefile) to influence the process.maketarget and
makevarUse:Two common targets in a Makefile
are all and clean.
Typically, invoking all will rebuild the
application, and invoking clean will remove
the temporary files (.o for example) created by
the build process.clean may be controlled by a number of
variables, including CLOBBER and
RECURSE.]]>Appearance:Two common targets in a Makefile are
all and
clean.Typically, invoking all will rebuild
the application, and invoking clean will
remove the temporary files (.o for example)
created by the build process.clean may be controlled by a number
of variables, including CLOBBER and
RECURSE.Literal textYou will often need to include literal text in the
Handbook. This is text that is excerpted from another file, or
which should be copied from the Handbook into another file
verbatim.Some of the time, programlisting will be
sufficient to denote this text. programlisting
is not always appropriate, particularly when you want to include a
portion of a file in-line with the rest of the
paragraph.On these occasions, use literal.literalUse:The maxusers 10 line in the kernel
configuration file determines the size of many system tables, and is
a rough guide to how many simultaneous logins the system will
support.]]>Appearance:The maxusers 10 line in the kernel
configuration file determines the size of many system tables, and
is a rough guide to how many simultaneous logins the system will
support.Showing items that the user must fill
inThere will often be times when you want to show the user what to
do, or refer to a file, or command line, or similar, where the user
cannot simply copy the examples that you provide, but must instead
include some information themselves.replaceable is designed for this eventuality.
Use it inside other elements to indicate parts
of that element's content that the user must replace.replaceableUse:&prompt.user; man command
]]>Appearance:&prompt.user; man commandreplaceable can be used in many different
elements, including literal. This example also
shows that replaceable should only be wrapped
around the content that the user is meant to
provide. The other content should be left alone.Use:The maxusers n
line in the kernel configuration file determines the size of many system
tables, and is a rough guide to how many simultaneous logins the system will
support.
For a desktop workstation, 32 is a good value
for n.]]>Appearance:The maxusers n
line in the kernel configuration file determines the size of many
system tables, and is a rough guide to how many simultaneous
logins the system will support.For a desktop workstation, 32 is a good
value for n.ImagesImage support in the documentation is currently extremely
experimental. I think the mechanisms described here are unlikely to
change, but that's not guaranteed.You will also need to install the
graphics/ImageMagick port, which is used to
convert between the different image formats. This is a big port,
and most of it is not required. However, while we're working on the
Makefiles and other infrastructure it makes
things easier. This port is not in the
textproc/docproj meta port, you must install it
by hand.The best example of what follows in practice is the
- en_US.ISO8859-1/articles/vm-design/ document.
+ doc/en_US.ISO8859-1/articles/vm-design/ document.
If you're unsure of the description that follows, take a look at the
files in that directory to see how everything hangs togther.
Experiment with creating different formatted versions of the
document to see how the image markup appears in the formatted
output.Image formatsWe currently support two formats for images. The format you
should use will depend on the nature of your image.For images that are primarily vector based, such as network
diagrams, timelines, and similar, use Encapsulated Postscript, and
make sure that your images have the .eps
extension.For bitmaps, such as screen captures, use the Portable Network
Graphic format, and make sure that your images have the
.png extension.These are the only formats in which images
should be committed to the CVS repository.Use the right format for the right image. It is to be expected
that your documentation will have a mix of EPS and PNG images. The
Makefiles ensure that the correct format image
is chosen depending on the output format that you use for your
documentation. Do not commit the same image to the
repository in two different formats.It is anticipated that the Documentation Project will switch to
using the Scalable Vector Graphic (SVG) format for vector images.
However, the current state of SVG capable editing tools makes this
impractical.MarkupThe markup for an image is relatively simple. First, markup a
mediaobject. The mediaobject
can contain other, more specific objects. We are concerned with
two, the imageobject and the
textobject.You should include one imageobject, and two
textobject elements. The
imageobject will point to the name of the image
file that will be used (without the extension). The
textobject elements contain information that will
be presented to the user as well as, or instead of, the
image.There are two circumstances where this can happen.When the reader is viewing the documentation in HTML. In
this case, each image will need to have associated alternate
text to show the user, typically whilst the image is loading, or
if they hover the mouse pointer over the image.When the reader is viewing the documentation in plain text.
In this case, each image should have an ASCII art equivalent to
show the user.An example will probably make things easier to understand.
Suppose you have an image, called fig1, that
you want to include in the document. This image is of a rectangle
with an A inside it. The markup for this would be as
follows.<mediaobject>
<imageobject>
<imagedata fileref="fig1">
</imageobject>
<textobject>
<literallayout class="monospaced">+---------------+
| A |
+---------------+</literallayout>
</textobject>
<textobject>
<phrase>A picture</phrase>
</textobject>
</mediaobject>Include an imagedata element inside the
imageobject element. The
fileref attribute should contain the filename
of the image to include, without the extension. The stylesheets
will work out which extension should be added to the filename
automatically.The first textobject should contain a
literallayout element, where the
class attribute is set to
monospaced. This is your opportunity to
demonstrate your ASCII art skills. This content will be used if
the document is converted to plain text.Notice how the first and last lines of the content of the
literallayout element butt up next to the
element's tags. This ensures no extraneous white space is
included.The second textobject should contain a
single phrase element. The contents of this
will become the alt attribute for the image
when this document is converted to HTML.Makefile entriesYour images must be listed in the
Makefile in the IMAGES
variable. This variable should contain the name of all your
source images. For example, if you have
created three figures, fig1.eps,
fig2.png, fig3.png, then
your Makefile should have lines like this in
it.…
IMAGES= fig1.eps fig2.png fig3.png
…or…
IMAGES= fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
…Again, the Makefile will work out the
complete list of images it needs to build your source document, you
only need to list the image files you
provided.Images and chapters in subdirectoriesYou must be careful when you separate your documentation in to
smaller files (see ) in
different directories.Suppose you have a book with three chapters, and the chapters
are stored in their own directories, called
chapter1/chapter.sgml,
chapter2/chapter.sgml, and
chapter3/chapter.sgml. If each chapter has
images associated with it, I suggest you place those images in each
chapter's subdirectory (chapter1/,
chapter2/, and
chapter3/).However, if you do this you must include the directory names in
the IMAGES variable in the
Makefile, and you must
include the directory name in the imagedata
element in your document.For example, if you have chapter1/fig1.png,
then chapter1/chapter.sgml should
contain<mediaobject>
<imageobject>
<imagedata fileref="chapter1/fig1">
</imageobject>
…
</mediaobject>The directory name must be included in the
fileref attributeThe Makefile must contain…
IMAGES= chapter1/fig1.png
…Then everything should just work.LinksLinks are also in-line elements.Linking to other parts of the same documentLinking within the same document requires you to specify
where you are linking from (i.e., the text the user will click, or
otherwise indicate, as the source of the link) and where you are
linking to (the link's destination).Each element within DocBook has an attribute called
id. You can place text in this attribute to
uniquely name the element it is attached to.This value will be used when you specify the link
source.Normally, you will only be linking to chapters or sections, so
you would add the id attribute to these
elements.id on chapters and sectionsIntroductionThis is the introduction. It contains a subsection,
which is identified as well.Sub-sect 1This is the subsection.
]]>Obviously, you should use more descriptive values. The values
must be unique within the document (i.e., not just the file, but the
document the file might be included in as well). Notice how the
id for the subsection is constructed by appending
text to the id of the chapter. This helps to
ensure that they are unique.If you want to allow the user to jump into a specific portion of
the document (possibly in the middle of a paragraph or an example),
use anchor. This element has no content, but
takes an id attribute.anchorThis paragraph has an embedded
link target in it. It won't show up in
the document.]]>When you want to provide the user with a link they can activate
(probably by clicking) to go to a section of the document that has
an id attribute, you can use either
xref or link.Both of these elements have a linkend
attribute. The value of this attribute should be the value that you
have used in a id attribute (it does not matter
if that value has not yet occurred in your document; this will work
for forward links as well as backward links).If you use xref then you have no control over
the text of the link. It will be generated for you.Using xrefAssume that this fragment appears somewhere in a document that
includes the id example;More information can be found
in .
More specific information can be found
in .]]>The text of the link will be generated automatically, and will
look like (emphasised text indicates the text
that will be the link);
More information can be found in Chapter
One.More specific information can be found in the
section called Sub-sect 1.
Notice how the text from the link is derived from the section
title or the chapter number.This means that you cannot use
xref to link to an id
attribute on an anchor element. The
anchor has no content, so the
xref cannot generate the text for the
link.If you want to control the text of the link then use
link. This element wraps content, and the
content will be used for the link.Using linkAssume that this fragment appears somewhere in a document that
includes the id example.More information can be found in
the first chapter.
More specific information can be found in
this section.]]>This will generate the following
(emphasised text indicates the text that will
be the link);
More information can be found in the first
chapter.More specific information can be found in
this section.
That last one is a bad example. Never use words like
this or here as the source for the
link. The reader will need to hunt around the surrounding context
to see where the link is actually taking them.You can use link to
include a link to an id on an
anchor element, since the
link content defines the text that will be used
for the link.Linking to documents on the WWWLinking to external documents is much simpler, as long as you
know the URL of the document you want to link to. Use
ulink. The url attribute is
the URL of the page that the link points to, and the content of the
element is the text that will be displayed for the user to
activate.ulinkUse:Of course, you could stop reading this document and
- go to the FreeBSD
+ go to the FreeBSD
home page instead.]]>Appearance:Of course, you could stop reading this document and go to the
- FreeBSD home page
+ FreeBSD home page
instead.
diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
index 1cf48fb8ab..fb1614180a 100644
--- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
@@ -1,218 +1,218 @@
The WebsitePreparationGet 200MB free disk space. You will need the disk space for the
SGML tools, a subset of the CVS tree, temporary build space and the
installed web pages. If you aready have installed the SGML tools and
the CVS tree, you need only ~100MB free disk space.Make sure your documentation ports are up to date! When in
doubt, remove the old ports using &man.pkg.delete.1; command before
installing the port. For example, we currently depend on
jade-1.2 and if you have installed jade-1.1, please do&prompt.root; pkg_delete jade-1.1Setup a CVS repository. You need the directories www, doc and
ports in the CVS tree (plus the CVSROOT of course). Please read the
CVSup introduction
- http://www.freebsd.org/handbook/synching.html#CVSUP how to
+ url="../handbook/synching.html#CVSUP">
+ http://www.FreeBSD.org/handbook/synching.html#CVSUP how to
mirror a CVS tree or parts of a CVS tree.The essential cvsup collections are: www,
doc-all, cvs-base, and
ports-base.These collections require ~100MB free disk space.A full CVS tree - including src,
doc, www, and
ports - is currently 650MB large.Build the web pages from scratchGo to into a build directory with at least 60MB of free
space.&prompt.root; mkdir /var/tmp/webbuild
&prompt.root; cd /var/tmp/webbuildCheckout the SGML files from the CVS tree.&prompt.root; cvs -R co www docChange in to the www directory, and
run the &man.make.1; links target, to
create the necessary symbolic links.&prompt.root; cd www
&prompt.root; make linksChange in to the en directory, and run
the &man.make.1; all target, to create
the web pages.&prompt.root; cd en
&prompt.root; make allInstall the web pages into your web serverIf you have moved out of the en
directory, change back to it.&prompt.root; cd path/www/enRun the &man.make.1; install target,
setting the DESTDIR variable to the name of the
directory you want to install the files to.&prompt.root; make DESTDIR=/usr/local/www installIf you have previously installed the web pages in to the same
directory the install process will not have deleted any old or
outdated pages. For example, if you build and install a new copy
of the site every day, this command will find and delete all
files that have not been updated in three days.&prompt.root; find /usr/local/www -ctime 3 -print0 | xargs -0 rmEnvironment variablesCVSROOTLocation of the CVS tree. Essential.&prompt.root; CVSROOT=/home/ncvs; export CVSROOTENGLISH_ONLYIf set and not empty, the makefiles will build and
install only the English documents. All translations will be
ignored. E.g.:&prompt.root; make ENGLISH_ONLY=YES all installIf you want unset the variable
ENGLISH_ONLY and build all pages, including
translations, set the variable ENGLISH_ONLY
to an empty value&prompt.root; make ENGLISH_ONLY="" all install cleanWEB_ONLYIf set and not empty, the makefiles wil build and install
only the HTML pages from the www directory. All documents from
the doc directory (Handbook, FAQ, Tutorials) will be ignored.
E.g.:&prompt.root; make WEB_ONLY=YES all installNOPORTSCVSIf set, the makefiles will not checkout files from the ports
cvs repository. Instead, it will copy the files from
/usr/ports (or where the variable
PORTSBASE points to).CVSROOT is an environment variable. You must set it
on the commandline or in your dot files (~/.profile).WEB_ONLY, ENGLISH_ONLY and
NOPORTSCVS are makefile variables. You can set the
variables in /etc/make.conf,
Makefile.inc or as environment variables on the
commandline or in your dot files.
diff --git a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml
index b5ebbeb5ad..43e1f0b044 100644
--- a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml
@@ -1,482 +1,482 @@
TranslationsThis is the FAQ for people translating the FreeBSD documentation
(FAQ, Handbook, tutorials, man pages, and others) to different
languages.It is very heavily based on the translation FAQ
from the FreeBSD German Documentation Project, originally written by Frank
Gründer elwood@mc5sys.in-berlin.de and translated back to
English by Bernd Warken bwarken@mayn.de.The FAQ maintainer is Nik Clayton
nik@FreeBSD.org.Why a FAQ?More and more people are approaching the freebsd-doc mailing
list and volunteering to translate FreeBSD documentation to other
languages. This FAQ aims to answer their questions so they can start
translating documentation as quickly as possible.What do i18n and l10n
mean?i18n means
internationalisation and l10n
means localisation. They are just a convenient
shorthand.i18n can be read as i followed by
18 letters, followed by n. Similarly,
l10n is l followed by 10 letters,
followed by n.Is there a mailing list for translators?Yes, freebsd-translate@ngo.org.uk. Subscribe by
sending a message to
freebsd-translate-request@ngo.org.uk with the word
subscribe in the body of the message.You will receive a reply asking you to confirm your subscription
(in exactly the same manner as the FreeBSD lists at FreeBSD.org).The primary language of the mailing list is English. However,
posts in other languages will be accepted. The mailing list is not
moderated, but you need to be a member of the list before you can
post to it.The mailing list is archived, but they are not currently
searchable. Sending the message help to
majordomo@ngo.org.uk will send back instructions on
how to access the archive.It is expected that the mailing list will transfer to FreeBSD.org and therefore become
official in the near future.Are more translators needed?Yes. The more people work on translation the faster it gets
done, and the faster changes to the English documentation are
mirrored in the translated documents.You do not have to be a professional translator to be able to
help.What languages do I need to know?Ideally, you will have a good knowledge of written English, and
obviously you will need to be fluent in the language you are
translating to.English is not strictly necessary. For example, you could do a
Hungarian translation of the FAQ from the Spanish
translation.What software do I need to know?It is strongly recommended that you maintain a local copy of the
FreeBSD CVS repository (at least the documentation part) either
using CTM or
CVSup. The "Staying current with FreeBSD"
chapter in the Handbook explains how to use these
applications.You should be comfortable using CVS.
This will allow you to see what has changed between different
versions of the files that make up the documentation.[XXX To Do -- write a tutorial that shows how to use CVSup to
get just the documentation, check it out, and see what's changed
between two arbitrary revisions]How do I find out who else might be translating to the same
language?The Documentation
+ url="../../../../docproj/translations.html">Documentation
Project translations page lists the translation efforts
that are currently known about. If others are already working
on translating documentation to your language, please don't
duplicate their efforts. Instead, contact them to see how you can
help.If no one is listed on that page as translating for your
language, then send a message to
freebsd-doc@FreeBSD.org in case someone else is
thinking of doing a translation, but hasn't announced it yet.No one else is translating to my language. What do I do?Congratulations, you have just started the FreeBSD
your-language-here Documentation
Translation Project. Welcome aboard.First, decide whether or not you've got the time to spare. Since
you are the only person working on your language at the moment it is
going to be your responsibility to publicise your work and
coordinate any volunteers that might want to help you.Write an e-mail to the Documentation Project mailing list,
announcing that you are going to translate the documentation, so the
Documentation Project translations page can be maintained.You should subscribe to the
freebsd-translate@ngo.org.uk mailing list (as
described earlier).If there is already someone in your country providing FreeBSD
mirroring services you should contact them and ask if you can
have some webspace for your project, and possibly an e-mail
address or mailing list services.Then pick a document and start translating. It is best to start
with something fairly small—either the FAQ, or one of the
tutorials.I've translated some documentation, where do I send it?That depends. If you are already working with a translation team
(such as the Japanese team, or the German team) then they will have
their own procedures for handling submitted documentation, and these
will be outlined on their web pages.If you are the only person working on a particular language (or
you are responsible for a translation project and want to submit
your changes back to the FreeBSD project) then you should send your
translation to the FreeBSD project (see the next question).I'm the only person working on translating to this language, how
do I submit my translation?orWe're a translation team, and want to submit documentation that
our members have translated for us?First, make sure your translation is organised properly. This
means that it should drop in to the existing documentation tree and
build straight away.Currently, the FreeBSD documentation is stored in a top level
directory called doc/. Directories below this
are named according to the language code they are written in, as
defined in ISO639 (/usr/share/misc/iso639 on a
version of FreeBSD newer than 20th January 1999).If your language can be encoded in different ways (for example,
Chinese) then there should be directories below this, one for each
encoding format you have provided.Finally, you should have directories for each document.For example, a hypothetical Swedish translation might look
likedoc/
sv_SE.ISO8859-1/
Makefile
books/
faq/
Makefile
book.sgmlsv_SE.ISO8859-1 is the name of the
translation, in
lang.encoding
form. Note the
two Makefiles, which will be used to build the documentation.Use &man.tar.1; and &man.gzip.1; to compress up your
documentation, and send it to the project.&prompt.user; cd doc
&prompt.user; tar cf swedish-docs.tar sv
&prompt.user; gzip -9 swedish-docs.tarPut swedish-docs.tar.gz somewhere. If you
do not have access to your own webspace (perhaps your ISP does not
let you have any) then you can e-mail Nik Clayton
nik@FreeBSD.org, and arrange to e-mail the files
when it is convenient.Either way, you should use &man.send-pr.1; to submit a report
indicating that you have submitted the documentation. It would be
very helpful if you could get other people to look over your
translation and double check it first, since it is unlikely that the
person committing it will be fluent in the language.Someone (probably the Documentation Project Manager, currently
Nik Clayton nik@FreeBSD.org) will then take your
translation and confirm that it builds. In particular, the
following things will be looked at:Do all your files use RCS strings (such as "ID")?Does make all in the
sv_SE.ISO8859-1 directory work correctly?Does make install work correctly?If there are any problems then whoever is looking at the
submission will get back to you to try and work them out.If there are no problems your translation will be committed
as soon as possible.Can I include language or country specific text in my
translation?We would prefer that you did not.For example, suppose that you are translating the Handbook to
Korean, and want to include a section about retailers in Korea in
your Handbook.There's no real reason why that information should not be in the
English (or German, or Spanish, or Japanese, or …) versions
as well. It is feasible that an English speaker in Korea might try
and pick up a copy of FreeBSD whilst over there. It also helps
increase FreeBSD's perceived presence around the globe, which is not
a bad thing.If you have country specific information, please submit it as a
change to the English Handbook (using &man.send-pr.1;) and then
translate the change back to your language in the translated
Handbook.Thanks.How should language specific characters be included?Non-ASCII characters in the documentation should be included
using SGML entities.Briefly, these look like an ampersand (&), the name of the
entity, and a semi-colon (;).The entity names are defined in ISO8879, which is in the ports
tree as textproc/iso8879.A few examples includeEntityAppearanceDescriptionééSmall e with an acute accentÉÉLarge E with an acute accentüüSmall u with an umlautAfter you have installed the iso8879 port, the files in
/usr/local/share/sgml/iso8879 contain the
complete list.Addressing the readerIn the English documents, the reader is addressed as
you, there is no formal/informal distinction as there
is in some languages.If you are translating to a language which does distinguish, use
whichever form is typically used in other technical documentation in
your language. If in doubt, use a mildly polite form.Do I need to include any additional information in my
translations?Yes.The header of the English version of each document will look
something like this;<!--
The FreeBSD Documentation Project
$FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $
-->The exact boilerplate may change, but it will always include a
$FreeBSD$ line and the phrase The FreeBSD Documentation
Project.
Note that the $FreeBSD part is expanded automatically by
CVS, so it should be empty (just
$FreeBSD$) for new files.Your translated documents should include their own
$FreeBSD$ line, and change the
FreeBSD Documentation Project line to
The FreeBSD language
Documentation Project.In addition, you should add a third line which indicates which
revision of the English text this is based on.So, the Spanish version of this file might start<!--
The FreeBSD Spanish Documentation Project
$FreeBSD: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $
Original revision: 1.11
-->
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
index 18c1e0ecdc..7112678304 100644
--- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
@@ -1,388 +1,388 @@
Writing styleIn order to promote consistency between the myriad authors of the
FreeBSD documentation, some guidelines have been drawn up for authors to
follow.Do not use contractionsDo not use contractions. Always spell the phrase out in full.
Don't use contractions would be wrong.Avoiding contractions makes for a more formal tone, is more
precise, and is slightly easier for translators.Use the serial commaIn a list of items within a paragraph, separate each item from
the others with a comma. Seperate the last item from the others with
a comma and the word and.For example, look at the following:
This is a list of one, two and three items.
Is this a list of three items, one,
two, and three, or a list of two items,
one and two and three?It is better to be explicit and include a serial comma:
This is a list of one, two, and three items.
Avoid redundant phrasesTry not to use redundant phrases. In particular, the
command, the file, and man
command are probably redundant.These two examples show this for commands. The second example
is preferred.Use the command cvsup to update your
sourcesUse cvsup to update your sourcesThese two examples show this for filenames. The second example
is preferred.… in the filename
/etc/rc.local…… in
/etc/rc.local…These two examples show this for manual references. The second
example is preferred (the second example uses
citerefentry).See man csh for more
information.See &man.csh.1;Two spaces at the end of sentencesAlways use two spaces at the end of sentences, as this
improves readability, and eases use of tools such as
emacs.While it may be argued that a capital letter following
a period denotes a new sentence, this is not the case, especially
in name usage. Jordan K. Hubbard is a good
example; it has a capital H following a
period and a space, and there certainly isn't a new sentence
there.For more information about writing style, see Elements of
+ url="http://www.bartleby.com/141/">Elements of
Style, by William Strunk.Style guideTo keep the source for the Handbook consistent when many different
people are editing it, please follow these style conventions.Letter caseTags are entered in lower case, <para>,
not<PARA>.Text that appears in SGML contexts is generally written in upper
case, <!ENTITY…>, and
<!DOCTYPE…>, not<!entity…> and
<!doctype…>.IndentationEach file starts with indentation set at column 0,
regardless of the indentation level of the file
which might contain this one.Every start tag increases the indentation level by 2 spaces, and
every end tag decreases the indentation level by 2 spaces. Replace
as many leading spaces with tabs as appropriate. Do not use
spaces in front of tabs, and do not add extraneous whitespace at the
end of a line. Content
within elements should be indented by two spaces if the content runs
over more than one line.For example, the source for this section looks something
like:......IndentationEach file starts with indentation set at column 0,
regardless of the indentation level of the file
which might contain this one.Every start tag increases the indentation level by 2 spaces, and
every end tag decreases the indentation level by 2 spaces. Content
within elements should be indented by two spaces if the content runs
over more than one line.
...
]]>
If you use Emacs or
Xemacs to edit the files then
sgml-mode should be loaded automatically, and the
Emacs local variables at the bottom of each file should enforce these
styles.Tag styleTag spacingTags that start at the same indent as a previous tag
should be separated by a blank line, and those that are not
at the same indent as a previous tag should not:NISOctober 1999
...
...
...............
]]>Separating tagsTags like itemizedlist which will
always have further tags inside them, and in fact don't take
character data themselves, are always on a line by
themselves.Tags like para and
term don't need other tags to contain
normal character data, and their contents begin immediately
after the tag, on the same line.The same applies to when these two types of tags
close.This leads to an obvious problem when mixing these
tags.When a starting tag which cannot contain character data
directly follows a tag of the type that requires other tags
within it to use character data, they are on separate lines.
The second tag should be properly indented.When a tag which can contain character data closes
directly after a tag which cannot contain character data
closes, they co-exist on the same line.White space changesWhen committing changes, do not commit changes to the
content at the same time as changes to the
formatting.This is so that the teams that convert the Handbook to other
languages can quickly see what content has actually changed in your
commit, without having to decide whether a line has changed because of
the content, or just because it has been refilled.For example, if you have added two sentences to a paragraph, such
that the line lengths on the paragraph now go over 80 columns, first
commit your change with the too-long line lengths. Then fix the line
wrapping, and commit this second change. In the commit message for
the second change, be sure to indicate that this is a whitespace-only
change, and that the translation team can ignore it.Word listThe following is a small list of words spelled the way they
should be used in the FreeBSD Documentation Project. If the
word you are looking for is not in this list, then please
consult the O'Reilly
word list.2.2.X4.X-STABLEDoS (Denial of Service)FreeBSD Ports CollectionInternetCDROMMHzports collectionUnixemailmanual page(s)mail servername serverweb server